« back to all changes in this revision
Viewing changes to Doc/Manual/SWIGDocumentation.html
- browse files at revision 13
- compare with another revision
- download diff
- download tarball
- view history from revision 13
- Committer: Bazaar Package Importer
- Author(s): Matthias Klose
- Date: 2007-12-06 10:27:08 UTC
- mfrom: (1.2.6 upstream)
- Revision ID: james.westby@ubuntu.com-20071206102708-t37t62i45n595w0e
Tags: 1.3.33-2ubuntu1
* Merge with Debian; remaining changes:
- Drop support for pike.
- Use python2.5 instead of python2.4.
- Clean Runtime/ as well.
- Force a few environment variables.
* debian/Rules (clean): Remove Lib/ocaml/swigp4.ml.
- Drop support for pike.
- Use python2.5 instead of python2.4.
- Clean Runtime/ as well.
- Force a few environment variables.
* debian/Rules (clean): Remove Lib/ocaml/swigp4.ml.
- files added:
- Doc/Devel/cmdopt.html
- Examples/lua/import
- Examples/python/docstrings
- Examples/tcl/std_vector
- files removed:
- Examples/csharp/extend/main.java
- Examples/java/mpointer
- Examples/perl5/mpointer
- Examples/python/mpointer
- Examples/ruby/mpointer
- Examples/tcl/mpointer
- files modified:
- ANNOUNCE
- Tools/vcfilter *
added
removed
Doc/Manual/SWIGDocumentation.html
156
156
</UL>
157
157
<B><A HREF="#Windows">3 Getting started on Windows</A></B>
158
158
<UL>
159
<LI><A HREF="#Windows_nn2">3.1 Installation on Windows</A>
160
<UL>
161
<LI><A HREF="#Windows_nn3">3.1.1 Windows Executable</A></LI>
162
</UL>
163
</LI>
164
<LI><A HREF="#examples">3.2 SWIG Windows Examples</A>
165
<UL>
166
<LI><A HREF="#Windows_nn5">3.2.1 Instructions for using the Examples
167
with Visual Studio</A>
168
<UL>
169
<LI><A HREF="#Windows_nn6">3.2.1.1 Python</A></LI>
170
<LI><A HREF="#Windows_nn7">3.2.1.2 TCL</A></LI>
171
<LI><A HREF="#Windows_nn8">3.2.1.3 Perl</A></LI>
172
<LI><A HREF="#Windows_nn9">3.2.1.4 Java</A></LI>
173
<LI><A HREF="#Windows_nn10">3.2.1.5 Ruby</A></LI>
174
<LI><A HREF="#Windows_nn11">3.2.1.6 C#</A></LI>
175
</UL>
176
</LI>
177
<LI><A HREF="#Windows_nn12">3.2.2 Instructions for using the Examples
178
with other compilers</A></LI>
179
</UL>
180
</LI>
181
<LI><A HREF="#Windows_nn13">3.3 SWIG on Cygwin and MinGW</A>
182
<UL>
183
<LI><A HREF="#swig_exe">3.3.1 Building swig.exe on Windows</A>
159
<LI><A HREF="#Windows_installation">3.1 Installation on Windows</A>
160
<UL>
161
<LI><A HREF="#Windows_executable">3.1.1 Windows Executable</A></LI>
162
</UL>
163
</LI>
164
<LI><A HREF="#Windows_examples">3.2 SWIG Windows Examples</A>
165
<UL>
166
<LI><A HREF="#Windows_visual_studio">3.2.1 Instructions for using the
167
Examples with Visual Studio</A>
168
<UL>
169
<LI><A HREF="#Windows_csharp">3.2.1.1 C#</A></LI>
170
<LI><A HREF="#Windows_java">3.2.1.2 Java</A></LI>
171
<LI><A HREF="#Windows_perl">3.2.1.3 Perl</A></LI>
172
<LI><A HREF="#Windows_python">3.2.1.4 Python</A></LI>
173
<LI><A HREF="#Windows_tcl">3.2.1.5 TCL</A></LI>
174
<LI><A HREF="#Windows_r">3.2.1.6 R</A></LI>
175
<LI><A HREF="#Windows_ruby">3.2.1.7 Ruby</A></LI>
176
</UL>
177
</LI>
178
<LI><A HREF="#Windows_other_compilers">3.2.2 Instructions for using the
179
Examples with other compilers</A></LI>
180
</UL>
181
</LI>
182
<LI><A HREF="#Windows_cygwin_mingw">3.3 SWIG on Cygwin and MinGW</A>
183
<UL>
184
<LI><A HREF="#Windows_swig_exe">3.3.1 Building swig.exe on Windows</A>
184
185
<UL>
185
186
<LI><A HREF="#Windows_mingw_msys">3.3.1.1 Building swig.exe using MinGW
186
187
and MSYS</A></LI>
187
<LI><A HREF="#Windows_nn16">3.3.1.2 Building swig.exe using Cygwin</A></LI>
188
<LI><A HREF="#Windows_nn17">3.3.1.3 Building swig.exe alternatives</A></LI>
188
<LI><A HREF="#Windows_cygwin">3.3.1.2 Building swig.exe using Cygwin</A></LI>
189
<LI><A HREF="#Windows_building_alternatives">3.3.1.3 Building swig.exe
190
alternatives</A></LI>
189
191
</UL>
190
192
</LI>
191
<LI><A HREF="#examples_cygwin">3.3.2 Running the examples on Windows
192
using Cygwin</A></LI>
193
<LI><A HREF="#Windows_examples_cygwin">3.3.2 Running the examples on
194
Windows using Cygwin</A></LI>
193
195
</UL>
194
196
</LI>
195
197
<LI><A HREF="#Windows_interface_file">3.4 Microsoft extensions and other
256
258
<LI><A HREF="#SWIG_nn26">5.4.5 Arrays</A></LI>
257
259
<LI><A HREF="#SWIG_readonly_variables">5.4.6 Creating read-only
258
260
variables</A></LI>
259
<LI><A HREF="#SWIG_nn28">5.4.7 Renaming and ignoring declarations</A></LI>
261
<LI><A HREF="#SWIG_rename_ignore">5.4.7 Renaming and ignoring
262
declarations</A></LI>
260
263
<LI><A HREF="#SWIG_default_args">5.4.8 Default/optional arguments</A></LI>
261
264
<LI><A HREF="#SWIG_nn30">5.4.9 Pointers to functions and callbacks</A></LI>
262
265
</UL>
340
343
</UL>
341
344
</LI>
342
345
<LI><A HREF="#SWIGPlus_nn28">6.16 Wrapping overloaded operators</A></LI>
343
<LI><A HREF="#SWIGPlus_nn29">6.17 Class extension</A></LI>
346
<LI><A HREF="#SWIGPlus_class_extension">6.17 Class extension</A></LI>
344
347
<LI><A HREF="#SWIGPlus_nn30">6.18 Templates</A></LI>
345
348
<LI><A HREF="#SWIGPlus_nn31">6.19 Namespaces</A></LI>
346
<LI><A HREF="#SWIGPlus_exception_specifications">6.20 Exception
349
<LI><A HREF="#SWIGPlus_renaming_templated_types_namespaces">6.20
350
Renaming templated types in namespaces</A></LI>
351
<LI><A HREF="#SWIGPlus_exception_specifications">6.21 Exception
347
352
specifications</A></LI>
348
<LI><A HREF="#SWIGPlus_catches">6.21 Exception handling with %catches</A>
349
</LI>
350
<LI><A HREF="#SWIGPlus_nn33">6.22 Pointers to Members</A></LI>
351
<LI><A HREF="#SWIGPlus_nn34">6.23 Smart pointers and operator->()</A></LI>
352
<LI><A HREF="#SWIGPlus_nn35">6.24 Using declarations and inheritance</A></LI>
353
<LI><A HREF="#SWIGPlus_nested_classes">6.25 Nested classes</A></LI>
354
<LI><A HREF="#SWIGPlus_nn37">6.26 A brief rant about const-correctness</A>
355
</LI>
356
<LI><A HREF="#SWIGPlus_nn42">6.27 Where to go for more information</A></LI>
353
<LI><A HREF="#SWIGPlus_catches">6.22 Exception handling with %catches</A>
354
</LI>
355
<LI><A HREF="#SWIGPlus_nn33">6.23 Pointers to Members</A></LI>
356
<LI><A HREF="#SWIGPlus_nn34">6.24 Smart pointers and operator->()</A></LI>
357
<LI><A HREF="#SWIGPlus_nn35">6.25 Using declarations and inheritance</A></LI>
358
<LI><A HREF="#SWIGPlus_nested_classes">6.26 Nested classes</A></LI>
359
<LI><A HREF="#SWIGPlus_nn37">6.27 A brief rant about const-correctness</A>
360
</LI>
361
<LI><A HREF="#SWIGPlus_nn42">6.28 Where to go for more information</A></LI>
357
362
</UL>
358
363
<B><A HREF="#Preprocessor">7 Preprocessing</A></B>
359
364
<UL>
364
369
<LI><A HREF="#Preprocessor_nn5">7.4 Macro Expansion</A></LI>
365
370
<LI><A HREF="#Preprocessor_nn6">7.5 SWIG Macros</A></LI>
366
371
<LI><A HREF="#Preprocessor_nn7">7.6 C99 and GNU Extensions</A></LI>
367
<LI><A HREF="#Preprocessor_nn8">7.7 Preprocessing and %{ ... %} blocks</A>
372
<LI><A HREF="#Preprocessor_nn8">7.7 Preprocessing and %{ ... %} & " ...
373
" delimiters</A></LI>
374
<LI><A HREF="#Preprocessor_nn9">7.8 Preprocessing and { ... } delimiters</A>
368
375
</LI>
369
<LI><A HREF="#Preprocessor_nn9">7.8 Preprocessing and { ... }</A></LI>
370
<LI><A HREF="#Preprocessor_nn10">7.9 Viewing preprocessor output</A></LI>
371
<LI><A HREF="#Preprocessor_warning_error">7.10 The #error and #warning
376
<LI><A HREF="#Preprocessor_typemap_delimiters">7.9 Preprocessor and
377
Typemaps</A></LI>
378
<LI><A HREF="#Preprocessor_nn10">7.10 Viewing preprocessor output</A></LI>
379
<LI><A HREF="#Preprocessor_warning_error">7.11 The #error and #warning
372
380
directives</A></LI>
373
381
</UL>
374
382
<B><A HREF="#Library">8 SWIG library</A></B>
459
467
<UL>
460
468
<LI><A HREF="#Typemaps_nn22">10.4.1 Scope</A></LI>
461
469
<LI><A HREF="#Typemaps_nn23">10.4.2 Declaring new local variables</A></LI>
462
<LI><A HREF="#Typemaps_nn24">10.4.3 Special variables</A></LI>
470
<LI><A HREF="#Typemaps_special_variables">10.4.3 Special variables</A></LI>
463
471
</UL>
464
472
</LI>
465
473
<LI><A HREF="#Typemaps_nn25">10.5 Common typemap methods</A>
555
563
<UL>
556
564
<LI><A HREF="#Warnings_nn2">14.1 Introduction</A></LI>
557
565
<LI><A HREF="#Warnings_suppression">14.2 Warning message suppression</A></LI>
558
<LI><A HREF="#Warnings_nn4">14.3 Enabling additional warnings</A></LI>
566
<LI><A HREF="#Warnings_nn4">14.3 Enabling extra warnings</A></LI>
559
567
<LI><A HREF="#Warnings_nn5">14.4 Issuing a warning message</A></LI>
560
<LI><A HREF="#Warnings_nn6">14.5 Commentary</A></LI>
561
<LI><A HREF="#Warnings_nn7">14.6 Warnings as errors</A></LI>
562
<LI><A HREF="#Warnings_nn8">14.7 Message output format</A></LI>
563
<LI><A HREF="#Warnings_nn9">14.8 Warning number reference</A>
568
<LI><A HREF="#Warnings_symbolic_symbols">14.5 Symbolic symbols</A></LI>
569
<LI><A HREF="#Warnings_nn6">14.6 Commentary</A></LI>
570
<LI><A HREF="#Warnings_nn7">14.7 Warnings as errors</A></LI>
571
<LI><A HREF="#Warnings_nn8">14.8 Message output format</A></LI>
572
<LI><A HREF="#Warnings_nn9">14.9 Warning number reference</A>
564
573
<UL>
565
<LI><A HREF="#Warnings_nn10">14.8.1 Deprecated features (100-199)</A></LI>
566
<LI><A HREF="#Warnings_nn11">14.8.2 Preprocessor (200-299)</A></LI>
567
<LI><A HREF="#Warnings_nn12">14.8.3 C/C++ Parser (300-399)</A></LI>
568
<LI><A HREF="#Warnings_nn13">14.8.4 Types and typemaps (400-499)</A></LI>
569
<LI><A HREF="#Warnings_nn14">14.8.5 Code generation (500-599)</A></LI>
570
<LI><A HREF="#Warnings_nn15">14.8.6 Language module specific (800-899)</A>
574
<LI><A HREF="#Warnings_nn10">14.9.1 Deprecated features (100-199)</A></LI>
575
<LI><A HREF="#Warnings_nn11">14.9.2 Preprocessor (200-299)</A></LI>
576
<LI><A HREF="#Warnings_nn12">14.9.3 C/C++ Parser (300-399)</A></LI>
577
<LI><A HREF="#Warnings_nn13">14.9.4 Types and typemaps (400-499)</A></LI>
578
<LI><A HREF="#Warnings_nn14">14.9.5 Code generation (500-599)</A></LI>
579
<LI><A HREF="#Warnings_nn15">14.9.6 Language module specific (800-899)</A>
571
580
</LI>
572
<LI><A HREF="#Warnings_nn16">14.8.7 User defined (900-999)</A></LI>
581
<LI><A HREF="#Warnings_nn16">14.9.7 User defined (900-999)</A></LI>
573
582
</UL>
574
583
</LI>
575
<LI><A HREF="#Warnings_nn17">14.9 History</A></LI>
584
<LI><A HREF="#Warnings_nn17">14.10 History</A></LI>
576
585
</UL>
577
586
<B><A HREF="#Modules">15 Working with Modules</A></B>
578
587
<UL>
579
<LI><A HREF="#Modules_nn2">15.1 The SWIG runtime code</A></LI>
580
<LI><A HREF="#external_run_time">15.2 External access to the runtime</A></LI>
581
<LI><A HREF="#Modules_nn4">15.3 A word of caution about static libraries</A>
588
<LI><A HREF="#Modules_nn1">15.1 Basics</A></LI>
589
<LI><A HREF="#Modules_nn2">15.2 The SWIG runtime code</A></LI>
590
<LI><A HREF="#external_run_time">15.3 External access to the runtime</A></LI>
591
<LI><A HREF="#Modules_nn4">15.4 A word of caution about static libraries</A>
582
592
</LI>
583
<LI><A HREF="#Modules_nn5">15.4 References</A></LI>
584
<LI><A HREF="#Modules_nn6">15.5 Reducing the wrapper file size</A></LI>
593
<LI><A HREF="#Modules_nn5">15.5 References</A></LI>
594
<LI><A HREF="#Modules_nn6">15.6 Reducing the wrapper file size</A></LI>
585
595
</UL>
586
596
<B><A HREF="#Allegrocl_nn1">16 SWIG and Allegro Common Lisp</A></B>
587
597
<UL>
719
729
management when returning references to member variables</A></LI>
720
730
<LI><A HREF="#csharp_memory_management_objects">17.5.2 Memory management
721
731
for objects passed to the C++ layer</A></LI>
732
<LI><A HREF="#csharp_date_marshalling">17.5.3 Date marshalling using the
733
csin typemap and associated attributes</A></LI>
734
<LI><A HREF="#csharp_date_properties">17.5.4 A date example
735
demonstrating marshalling of C# properties</A></LI>
736
<LI><A HREF="#csharp_partial_classes">17.5.5 Turning wrapped classes
737
into partial classes</A></LI>
738
<LI><A HREF="#csharp_extending_proxy_class">17.5.6 Extending proxy
739
classes with additional C# code</A></LI>
722
740
</UL>
723
741
</LI>
724
742
</UL>
877
895
collection</A></LI>
878
896
<LI><A HREF="#java_pgcpp">20.4.3.4 The premature garbage collection
879
897
prevention parameter for proxy class marshalling</A></LI>
898
<LI><A HREF="#java_multithread_libraries">20.4.3.5 Single threaded
899
applications and thread safety</A></LI>
880
900
</UL>
881
901
</LI>
882
902
<LI><A HREF="#type_wrapper_classes">20.4.4 Type wrapper classes</A></LI>
919
939
<LI><A HREF="#simple_pointers">20.7.2 Simple pointers</A></LI>
920
940
<LI><A HREF="#c_arrays">20.7.3 Wrapping C arrays with Java arrays</A></LI>
921
941
<LI><A HREF="#unbounded_c_arrays">20.7.4 Unbounded C Arrays</A></LI>
942
<LI><A HREF="#java_heap_allocations">20.7.5 Overriding new and delete to
943
allocate from Java heap</A></LI>
922
944
</UL>
923
945
</LI>
924
946
<LI><A HREF="#java_typemaps">20.8 Java typemaps</A>
966
988
management when returning references to member variables</A></LI>
967
989
<LI><A HREF="#java_memory_management_objects">20.9.12 Memory management
968
990
for objects passed to the C++ layer</A></LI>
991
<LI><A HREF="#java_date_marshalling">20.9.13 Date marshalling using the
992
javain typemap and associated attributes</A></LI>
969
993
</UL>
970
994
</LI>
971
995
<LI><A HREF="#java_directors_faq">20.10 Living with Java Directors</A></LI>
989
1013
<LI><A HREF="#Lisp_nn4">21.2.1 Additional Commandline Options</A></LI>
990
1014
<LI><A HREF="#Lisp_nn5">21.2.2 Generating CFFI bindings</A></LI>
991
1015
<LI><A HREF="#Lisp_nn6">21.2.3 Generating CFFI bindings for C++ code</A></LI>
1016
<LI><A HREF="#Lisp_nn7">21.2.4 Inserting user code into generated files</A>
1017
</LI>
992
1018
</UL>
993
1019
</LI>
994
<LI><A HREF="#Lisp_nn7">21.3 CLISP</A>
1020
<LI><A HREF="#Lisp_nn8">21.3 CLISP</A>
995
1021
<UL>
996
<LI><A HREF="#Lisp_nn8">21.3.1 Additional Commandline Options</A></LI>
997
<LI><A HREF="#Lisp_nn9">21.3.2 Details on CLISP bindings</A></LI>
1022
<LI><A HREF="#Lisp_nn9">21.3.1 Additional Commandline Options</A></LI>
1023
<LI><A HREF="#Lisp_nn10">21.3.2 Details on CLISP bindings</A></LI>
998
1024
</UL>
999
1025
</LI>
1000
<LI><A HREF="#Lisp_nn10">21.4 UFFI</A></LI>
1026
<LI><A HREF="#Lisp_nn11">21.4 UFFI</A></LI>
1001
1027
</UL>
1002
1028
<B><A HREF="#Lua_nn1">22 SWIG and Lua</A></B>
1003
1029
<UL>
1026
1052
<LI><A HREF="#Lua_nn19">22.3.12 Class extension with %extend</A></LI>
1027
1053
<LI><A HREF="#Lua_nn20">22.3.13 C++ templates</A></LI>
1028
1054
<LI><A HREF="#Lua_nn21">22.3.14 C++ Smart Pointers</A></LI>
1055
<LI><A HREF="#Lua_nn22">22.3.15 Writing your own custom wrappers</A></LI>
1029
1056
</UL>
1030
1057
</LI>
1031
<LI><A HREF="#Lua_nn22">22.4 Details on the Lua binding</A>
1058
<LI><A HREF="#Lua_nn23">22.4 Details on the Lua binding</A>
1032
1059
<UL>
1033
<LI><A HREF="#Lua_nn23">22.4.1 Binding global data into the module.</A></LI>
1034
<LI><A HREF="#Lua_nn24">22.4.2 Userdata and Metatables</A></LI>
1035
<LI><A HREF="#Lua_nn25">22.4.3 Memory management</A></LI>
1060
<LI><A HREF="#Lua_nn24">22.4.1 Binding global data into the module.</A></LI>
1061
<LI><A HREF="#Lua_nn25">22.4.2 Userdata and Metatables</A></LI>
1062
<LI><A HREF="#Lua_nn26">22.4.3 Memory management</A></LI>
1036
1063
</UL>
1037
1064
</LI>
1038
1065
</UL>
1260
1287
<LI><A HREF="#Python_nn3">29.2 Preliminaries</A>
1261
1288
<UL>
1262
1289
<LI><A HREF="#Python_nn4">29.2.1 Running SWIG</A></LI>
1263
<LI><A HREF="#Python_nn6">29.2.2 Compiling a dynamic module</A></LI>
1264
<LI><A HREF="#Python_nn7">29.2.3 Using distutils</A></LI>
1290
<LI><A HREF="#Python_nn6">29.2.2 Using distutils</A></LI>
1291
<LI><A HREF="#Python_nn7">29.2.3 Hand compiling a dynamic module</A></LI>
1265
1292
<LI><A HREF="#Python_nn8">29.2.4 Static linking</A></LI>
1266
1293
<LI><A HREF="#Python_nn9">29.2.5 Using your module</A></LI>
1267
1294
<LI><A HREF="#Python_nn10">29.2.6 Compilation of C++ extensions</A></LI>
1398
1425
<LI><A HREF="#Ruby_nn21">30.3.10 C++ Operators</A></LI>
1399
1426
<LI><A HREF="#Ruby_nn22">30.3.11 C++ namespaces</A></LI>
1400
1427
<LI><A HREF="#Ruby_nn23">30.3.12 C++ templates</A></LI>
1401
<LI><A HREF="#Ruby_nn24">30.3.13 C++ Smart Pointers</A></LI>
1402
<LI><A HREF="#Ruby_nn25">30.3.14 Cross-Language Polymorphism</A>
1428
<LI><A HREF="#Ruby_nn23_1">30.3.13 C++ Standard Template Library (STL)</A>
1429
</LI>
1430
<LI><A HREF="#C_STL_Functors">30.3.14 C++ STL Functors</A></LI>
1431
<LI><A HREF="#Ruby_C_Iterators">30.3.15 C++ STL Iterators</A></LI>
1432
<LI><A HREF="#Ruby_nn24">30.3.16 C++ Smart Pointers</A></LI>
1433
<LI><A HREF="#Ruby_nn25">30.3.17 Cross-Language Polymorphism</A>
1403
1434
<UL>
1404
<LI><A HREF="#Ruby_nn26">30.3.14.1 Exception Unrolling</A></LI>
1435
<LI><A HREF="#Ruby_nn26">30.3.17.1 Exception Unrolling</A></LI>
1405
1436
</UL>
1406
1437
</LI>
1407
1438
</UL>
1418
1449
<LI><A HREF="#Ruby_nn33">30.6 Exception handling</A>
1419
1450
<UL>
1420
1451
<LI><A HREF="#Ruby_nn34">30.6.1 Using the %exception directive</A></LI>
1421
<LI><A HREF="#Ruby_nn35">30.6.2 Raising exceptions</A></LI>
1422
<LI><A HREF="#Ruby_nn36">30.6.3 Exception classes</A></LI>
1452
<LI><A HREF="#Ruby_nn34_2">30.6.2 Handling Ruby Blocks</A></LI>
1453
<LI><A HREF="#Ruby_nn35">30.6.3 Raising exceptions</A></LI>
1454
<LI><A HREF="#Ruby_nn36">30.6.4 Exception classes</A></LI>
1423
1455
</UL>
1424
1456
</LI>
1425
1457
<LI><A HREF="#Ruby_nn37">30.7 Typemaps</A>
1426
1458
<UL>
1427
1459
<LI><A HREF="#Ruby_nn38">30.7.1 What is a typemap?</A></LI>
1428
<LI><A HREF="#Ruby_nn39">30.7.2 Ruby typemaps</A></LI>
1429
<LI><A HREF="#Ruby_nn40">30.7.3 Typemap variables</A></LI>
1430
<LI><A HREF="#Ruby_nn41">30.7.4 Useful Functions</A>
1431
<UL>
1432
<LI><A HREF="#Ruby_nn42">30.7.4.1 C Datatypes to Ruby Objects</A></LI>
1433
<LI><A HREF="#Ruby_nn43">30.7.4.2 Ruby Objects to C Datatypes</A></LI>
1434
<LI><A HREF="#Ruby_nn44">30.7.4.3 Macros for VALUE</A></LI>
1435
<LI><A HREF="#Ruby_nn45">30.7.4.4 Exceptions</A></LI>
1436
<LI><A HREF="#Ruby_nn46">30.7.4.5 Iterators</A></LI>
1437
</UL>
1438
</LI>
1439
<LI><A HREF="#Ruby_nn47">30.7.5 Typemap Examples</A></LI>
1440
<LI><A HREF="#Ruby_nn48">30.7.6 Converting a Ruby array to a char **</A></LI>
1441
<LI><A HREF="#Ruby_nn49">30.7.7 Collecting arguments in a hash</A></LI>
1442
<LI><A HREF="#Ruby_nn50">30.7.8 Pointer handling</A>
1443
<UL>
1444
<LI><A HREF="#Ruby_nn51">30.7.8.1 Ruby Datatype Wrapping</A></LI>
1445
</UL>
1446
</LI>
1447
<LI><A HREF="#Ruby_nn52">30.7.9 Example: STL Vector to Ruby Array</A></LI>
1448
</UL>
1449
</LI>
1450
<LI><A HREF="#Ruby_nn53">30.8 Advanced Topics</A>
1451
<UL>
1452
<LI><A HREF="#Ruby_nn54">30.8.1 Operator overloading</A></LI>
1453
<LI><A HREF="#Ruby_nn55">30.8.2 Creating Multi-Module Packages</A></LI>
1454
<LI><A HREF="#Ruby_nn56">30.8.3 Specifying Mixin Modules</A></LI>
1455
</UL>
1456
</LI>
1457
<LI><A HREF="#Ruby_nn57">30.9 Memory Management</A>
1458
<UL>
1459
<LI><A HREF="#Ruby_nn58">30.9.1 Mark and Sweep Garbage Collector</A></LI>
1460
<LI><A HREF="#Ruby_nn59">30.9.2 Object Ownership</A></LI>
1461
<LI><A HREF="#Ruby_nn60">30.9.3 Object Tracking</A></LI>
1462
<LI><A HREF="#Ruby_nn61">30.9.4 Mark Functions</A></LI>
1463
<LI><A HREF="#Ruby_nn62">30.9.5 Free Functions</A></LI>
1460
<LI><A HREF="#Ruby_Typemap_scope">30.7.2 Typemap scope</A></LI>
1461
<LI><A HREF="#Ruby_Copying_a_typemap">30.7.3 Copying a typemap</A></LI>
1462
<LI><A HREF="#Ruby_Deleting_a_typemap">30.7.4 Deleting a typemap</A></LI>
1463
<LI><A HREF="#Ruby_Placement_of_typemaps">30.7.5 Placement of typemaps</A>
1464
</LI>
1465
<LI><A HREF="#Ruby_nn39">30.7.6 Ruby typemaps</A>
1466
<UL>
1467
<LI><A HREF="#Ruby_in_typemap">30.7.6.1 "in" typemap</A></LI>
1468
<LI><A HREF="#Ruby_typecheck_typemap">30.7.6.2 "typecheck" typemap</A></LI>
1469
<LI><A HREF="#Ruby_out_typemap">30.7.6.3 "out" typemap</A></LI>
1470
<LI><A HREF="#Ruby_arginit_typemap">30.7.6.4 "arginit" typemap</A></LI>
1471
<LI><A HREF="#Ruby_default_typemap">30.7.6.5 "default" typemap</A></LI>
1472
<LI><A HREF="#Ruby_check_typemap">30.7.6.6 "check" typemap</A></LI>
1473
<LI><A HREF="#Ruby_argout_typemap_">30.7.6.7 "argout" typemap</A></LI>
1474
<LI><A HREF="#Ruby_freearg_typemap_">30.7.6.8 "freearg" typemap</A></LI>
1475
<LI><A HREF="#Ruby_newfree_typemap">30.7.6.9 "newfree" typemap</A></LI>
1476
<LI><A HREF="#Ruby_memberin_typemap">30.7.6.10 "memberin" typemap</A></LI>
1477
<LI><A HREF="#Ruby_varin_typemap">30.7.6.11 "varin" typemap</A></LI>
1478
<LI><A HREF="#Ruby_varout_typemap_">30.7.6.12 "varout" typemap</A></LI>
1479
<LI><A HREF="#Ruby_throws_typemap">30.7.6.13 "throws" typemap</A></LI>
1480
<LI><A HREF="#Ruby_directorin_typemap">30.7.6.14 directorin typemap</A></LI>
1481
<LI><A HREF="#Ruby_directorout_typemap">30.7.6.15 directorout typemap</A>
1482
</LI>
1483
<LI><A HREF="#Ruby_directorargout_typemap">30.7.6.16 directorargout
1484
typemap</A></LI>
1485
<LI><A HREF="#Ruby_ret_typemap">30.7.6.17 ret typemap</A></LI>
1486
<LI><A HREF="#Ruby_globalin_typemap">30.7.6.18 globalin typemap</A></LI>
1487
</UL>
1488
</LI>
1489
<LI><A HREF="#Ruby_nn40">30.7.7 Typemap variables</A></LI>
1490
<LI><A HREF="#Ruby_nn41">30.7.8 Useful Functions</A>
1491
<UL>
1492
<LI><A HREF="#Ruby_nn42">30.7.8.1 C Datatypes to Ruby Objects</A></LI>
1493
<LI><A HREF="#Ruby_nn43">30.7.8.2 Ruby Objects to C Datatypes</A></LI>
1494
<LI><A HREF="#Ruby_nn44">30.7.8.3 Macros for VALUE</A></LI>
1495
<LI><A HREF="#Ruby_nn45">30.7.8.4 Exceptions</A></LI>
1496
<LI><A HREF="#Ruby_nn46">30.7.8.5 Iterators</A></LI>
1497
</UL>
1498
</LI>
1499
<LI><A HREF="#Ruby_nn47">30.7.9 Typemap Examples</A></LI>
1500
<LI><A HREF="#Ruby_nn48">30.7.10 Converting a Ruby array to a char **</A>
1501
</LI>
1502
<LI><A HREF="#Ruby_nn49">30.7.11 Collecting arguments in a hash</A></LI>
1503
<LI><A HREF="#Ruby_nn50">30.7.12 Pointer handling</A>
1504
<UL>
1505
<LI><A HREF="#Ruby_nn51">30.7.12.1 Ruby Datatype Wrapping</A></LI>
1506
</UL>
1507
</LI>
1508
<LI><A HREF="#Ruby_nn52">30.7.13 Example: STL Vector to Ruby Array</A></LI>
1509
</UL>
1510
</LI>
1511
<LI><A HREF="#Ruby_nn65">30.8 Docstring Features</A>
1512
<UL>
1513
<LI><A HREF="#Ruby_nn66">30.8.1 Module docstring</A></LI>
1514
<LI><A HREF="#Ruby_nn67">30.8.2 %feature("autodoc")</A>
1515
<UL>
1516
<LI><A HREF="#Ruby_nn68">30.8.2.1 %feature("autodoc", "0")</A></LI>
1517
<LI><A HREF="#Ruby_autodoc1">30.8.2.2 %feature("autodoc", "1")</A></LI>
1518
<LI><A HREF="#Ruby_autodoc2">30.8.2.3 %feature("autodoc", "2")</A></LI>
1519
<LI><A HREF="#Ruby_feature_autodoc3">30.8.2.4 %feature("autodoc", "3")</A>
1520
</LI>
1521
<LI><A HREF="#Ruby_nn70">30.8.2.5 %feature("autodoc", "docstring")</A></LI>
1522
</UL>
1523
</LI>
1524
<LI><A HREF="#Ruby_nn71">30.8.3 %feature("docstring")</A></LI>
1525
</UL>
1526
</LI>
1527
<LI><A HREF="#Ruby_nn53">30.9 Advanced Topics</A>
1528
<UL>
1529
<LI><A HREF="#Ruby_nn54">30.9.1 Operator overloading</A></LI>
1530
<LI><A HREF="#Ruby_nn55">30.9.2 Creating Multi-Module Packages</A></LI>
1531
<LI><A HREF="#Ruby_nn56">30.9.3 Specifying Mixin Modules</A></LI>
1532
</UL>
1533
</LI>
1534
<LI><A HREF="#Ruby_nn57">30.10 Memory Management</A>
1535
<UL>
1536
<LI><A HREF="#Ruby_nn58">30.10.1 Mark and Sweep Garbage Collector</A></LI>
1537
<LI><A HREF="#Ruby_nn59">30.10.2 Object Ownership</A></LI>
1538
<LI><A HREF="#Ruby_nn60">30.10.3 Object Tracking</A></LI>
1539
<LI><A HREF="#Ruby_nn61">30.10.4 Mark Functions</A></LI>
1540
<LI><A HREF="#Ruby_nn62">30.10.5 Free Functions</A></LI>
1541
<LI><A HREF="#Ruby_nn63">30.10.6 Embedded Ruby and the C++ Stack</A></LI>
1464
1542
</UL>
1465
1543
</LI>
1466
1544
</UL>
1537
1615
<UL>
1538
1616
<LI><A HREF="#R_nn2">32.1 Bugs</A></LI>
1539
1617
<LI><A HREF="#R_nn3">32.2 Using R and SWIG</A></LI>
1540
<LI><A HREF="#R_nn4">32.3 General policy</A></LI>
1541
<LI><A HREF="#R_nn5">32.4 Language conventions</A></LI>
1542
<LI><A HREF="#R_nn6">32.5 C++ classes</A></LI>
1543
<LI><A HREF="#R_nn7">32.6 Enumerations</A></LI>
1618
<LI><A HREF="#R_nn4">32.3 Precompiling large R files</A></LI>
1619
<LI><A HREF="#R_nn5">32.4 General policy</A></LI>
1620
<LI><A HREF="#R_language_conventions">32.5 Language conventions</A></LI>
1621
<LI><A HREF="#R_nn6">32.6 C++ classes</A></LI>
1622
<LI><A HREF="#R_nn7">32.7 Enumerations</A></LI>
1544
1623
</UL>
1545
1624
<B><A HREF="#Extending">33 Extending SWIG to support new languages</A></B>
1546
1625
<UL>
1601
1680
<LI><A HREF="#Extending_nn43">33.10.12 Documentation</A></LI>
1602
1681
<LI><A HREF="#Extending_prerequisites">33.10.13 Prerequisites for adding
1603
1682
a new language module to the SWIG distribution</A></LI>
1683
<LI><A HREF="#Extending_coding_style_guidelines">33.10.14 Coding style
1684
guidelines</A></LI>
1604
1685
</UL>
1605
1686
</LI>
1606
1687
<LI><A HREF="#Extending_nn44">33.11 Typemaps</A>
1612
1693
</UL>
1613
1694
<HR NOSHADE>
1614
1695
<H1><A name="Sections"></A>SWIG-1.3 Development Documentation</H1>
1615
Last update : SWIG-1.3.31 (November 20, 2006)
1696
Last update : SWIG-1.3.33 (November 23, 2007)
1616
1697
<H2><A NAME="1_1">Sections</A></H2>
1617
1698
<P> The SWIG documentation is being updated to reflect new SWIG features
1618
1699
and enhancements. However, this update process is not quite
1743
1824
</DIV>
1744
1825
<P> The mailing list often discusses some of the more technical aspects
1745
1826
of SWIG along with information about beta releases and future work.</P>
1746
<P> CVS access to the latest version of SWIG is also available. More
1827
<P> SVN access to the latest version of SWIG is also available. More
1747
1828
information about this can be obtained at:</P>
1748
1829
<DIV class="shell">
1749
1830
<PRE>
1750
<A href="http://www.swig.org/cvs.html">http://www.swig.org/cvs.html</A>
1831
<A href="http://www.swig.org/svn.html">http://www.swig.org/svn.html</A>
1751
1832
</PRE>
1752
1833
</DIV>
1753
1834
<H2><A name="Preface_nn6"></A>1.5 Prerequisites</H2>
2215
2296
<!-- INDEX -->
2216
2297
<DIV class="sectiontoc">
2217
2298
<UL>
2218
<LI><A href="#Windows_nn2">Installation on Windows</A>
2219
<UL>
2220
<LI><A href="#Windows_nn3">Windows Executable</A></LI>
2221
</UL>
2222
</LI>
2223
<LI><A href="#examples">SWIG Windows Examples</A>
2224
<UL>
2225
<LI><A href="#Windows_nn5">Instructions for using the Examples with
2226
Visual Studio</A>
2227
<UL>
2228
<LI><A href="#Windows_nn6">Python</A></LI>
2229
<LI><A href="#Windows_nn7">TCL</A></LI>
2230
<LI><A href="#Windows_nn8">Perl</A></LI>
2231
<LI><A href="#Windows_nn9">Java</A></LI>
2232
<LI><A href="#Windows_nn10">Ruby</A></LI>
2233
<LI><A href="#Windows_nn11">C#</A></LI>
2234
</UL>
2235
</LI>
2236
<LI><A href="#Windows_nn12">Instructions for using the Examples with
2237
other compilers</A></LI>
2238
</UL>
2239
</LI>
2240
<LI><A href="#Windows_nn13">SWIG on Cygwin and MinGW</A>
2241
<UL>
2242
<LI><A href="#swig_exe">Building swig.exe on Windows</A>
2299
<LI><A href="#Windows_installation">Installation on Windows</A>
2300
<UL>
2301
<LI><A href="#Windows_executable">Windows Executable</A></LI>
2302
</UL>
2303
</LI>
2304
<LI><A href="#Windows_examples">SWIG Windows Examples</A>
2305
<UL>
2306
<LI><A href="#Windows_visual_studio">Instructions for using the Examples
2307
with Visual Studio</A>
2308
<UL>
2309
<LI><A href="#Windows_csharp">C#</A></LI>
2310
<LI><A href="#Windows_java">Java</A></LI>
2311
<LI><A href="#Windows_perl">Perl</A></LI>
2312
<LI><A href="#Windows_python">Python</A></LI>
2313
<LI><A href="#Windows_tcl">TCL</A></LI>
2314
<LI><A href="#Windows_r">R</A></LI>
2315
<LI><A href="#Windows_ruby">Ruby</A></LI>
2316
</UL>
2317
</LI>
2318
<LI><A href="#Windows_other_compilers">Instructions for using the
2319
Examples with other compilers</A></LI>
2320
</UL>
2321
</LI>
2322
<LI><A href="#Windows_cygwin_mingw">SWIG on Cygwin and MinGW</A>
2323
<UL>
2324
<LI><A href="#Windows_swig_exe">Building swig.exe on Windows</A>
2243
2325
<UL>
2244
2326
<LI><A href="#Windows_mingw_msys">Building swig.exe using MinGW and MSYS</A>
2245
2327
</LI>
2246
<LI><A href="#Windows_nn16">Building swig.exe using Cygwin</A></LI>
2247
<LI><A href="#Windows_nn17">Building swig.exe alternatives</A></LI>
2328
<LI><A href="#Windows_cygwin">Building swig.exe using Cygwin</A></LI>
2329
<LI><A href="#Windows_building_alternatives">Building swig.exe
2330
alternatives</A></LI>
2248
2331
</UL>
2249
2332
</LI>
2250
<LI><A href="#examples_cygwin">Running the examples on Windows using
2251
Cygwin</A></LI>
2333
<LI><A href="#Windows_examples_cygwin">Running the examples on Windows
2334
using Cygwin</A></LI>
2252
2335
</UL>
2253
2336
</LI>
2254
2337
<LI><A href="#Windows_interface_file">Microsoft extensions and other
2260
2343
SWIG and running the examples is covered as well as building the SWIG
2261
2344
executable. Usage within the Unix like environments MinGW and Cygwin is
2262
2345
also detailed.</P>
2263
<H2><A name="Windows_nn2"></A>3.1 Installation on Windows</H2>
2346
<H2><A name="Windows_installation"></A>3.1 Installation on Windows</H2>
2264
2347
<P> SWIG does not come with the usual Windows type installation program,
2265
2348
however it is quite easy to get started. The main steps are:</P>
2266
2349
<UL>
2271
2354
SWIG Windows Examples</A> section in order to run examples using Visual
2272
2355
C++.</LI>
2273
2356
</UL>
2274
<H3><A name="Windows_nn3"></A>3.1.1 Windows Executable</H3>
2357
<H3><A name="Windows_executable"></A>3.1.1 Windows Executable</H3>
2275
2358
<P> The swigwin distribution contains the SWIG Windows executable,
2276
2359
swig.exe, which will run on 32 bit versions of Windows, ie Windows
2277
2360
95/98/ME/NT/2000/XP. If you want to build your own swig.exe have a look
2278
2361
at <A href="#swig_exe">Building swig.exe on Windows</A>.</P>
2279
<H2><A name="examples"></A>3.2 SWIG Windows Examples</H2>
2362
<H2><A name="Windows_examples"></A>3.2 SWIG Windows Examples</H2>
2280
2363
<P> Using Microsoft Visual C++ is the most common approach to compiling
2281
2364
and linking SWIG's output. The Examples directory has a few Visual C++
2282
2365
project files (.dsp files). These were produced by Visual C++ 6,
2289
2372
examples using Cygwin</A>.</P>
2290
2373
<P> More information on each of the examples is available with the
2291
2374
examples distributed with SWIG (Examples/index.html).</P>
2292
<H3><A name="Windows_nn5"></A>3.2.1 Instructions for using the Examples
2293
with Visual Studio</H3>
2375
<H3><A name="Windows_visual_studio"></A>3.2.1 Instructions for using the
2376
Examples with Visual Studio</H3>
2294
2377
<P> Ensure the SWIG executable is as supplied in the SWIG root directory
2295
2378
in order for the examples to work. Most languages require some
2296
2379
environment variables to be set<B> before</B> running Visual C++. Note
2307
2390
coded values. If you are interested in how the project files are set up
2308
2391
there is explanatory information in some of the language module's
2309
2392
documentation.</P>
2310
<H4><A name="Windows_nn6"></A>3.2.1.1 Python</H4>
2393
<H4><A name="Windows_csharp"></A>3.2.1.1 C#</H4>
2394
<P> The C# examples do not require any environment variables to be set
2395
as a C# project file is included. Just open up the .sln solution file
2396
in Visual Studio .NET 2003 or later, select Release Build, and do a
2397
Rebuild All from the Build menu. The accompanying C# and C++ project
2398
files are automatically used by the solution file.</P>
2399
<H4><A name="Windows_java"></A>3.2.1.2 Java</H4>
2400
<P><B> <TT>JAVA_INCLUDE</TT></B> : Set this to the directory containing
2401
jni.h
2402
<BR><B> <TT>JAVA_BIN</TT></B> : Set this to the bin directory containing
2403
javac.exe</P>
2404
<P> Example using JDK1.3:
2405
<BR> <TT>JAVA_INCLUDE: D:\jdk1.3\include
2406
<BR> JAVA_BIN: D:\jdk1.3\bin
2407
<BR></TT></P>
2408
<H4><A name="Windows_perl"></A>3.2.1.3 Perl</H4>
2409
<P><B> <TT>PERL5_INCLUDE</TT></B> : Set this to the directory containing
2410
perl.h
2411
<BR><B> <TT>PERL5_LIB</TT></B> : Set this to the Perl library including
2412
path for linking</P>
2413
<P> Example using nsPerl 5.004_04:</P>
2414
<P> <TT>PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
2415
<BR> PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib
2416
<BR></TT></P>
2417
<H4><A name="Windows_python"></A>3.2.1.4 Python</H4>
2311
2418
<P><B> <TT>PYTHON_INCLUDE</TT></B> : Set this to the directory that
2312
2419
contains python.h
2313
2420
<BR><B> <TT>PYTHON_LIB</TT></B> : Set this to the python library
2314
2421
including path for linking</P>
2315
2422
<P> Example using Python 2.1.1:
2316
<BR> <TT>PYTHON_INCLUDE: d:\python21\include
2317
<BR> PYTHON_LIB: d:\python21\libs\python21.lib
2423
<BR> <TT>PYTHON_INCLUDE: D:\python21\include
2424
<BR> PYTHON_LIB: D:\python21\libs\python21.lib
2318
2425
<BR></TT></P>
2319
<H4><A name="Windows_nn7"></A>3.2.1.2 TCL</H4>
2426
<H4><A name="Windows_tcl"></A>3.2.1.5 TCL</H4>
2320
2427
<P><B> <TT>TCL_INCLUDE</TT></B> : Set this to the directory containing
2321
2428
tcl.h
2322
2429
<BR><B> <TT>TCL_LIB</TT></B> : Set this to the TCL library including
2323
2430
path for linking</P>
2324
2431
<P> Example using ActiveTcl 8.3.3.3
2325
<BR> <TT>TCL_INCLUDE: d:\tcl\include
2326
<BR> TCL_LIB: d:\tcl\lib\tcl83.lib
2327
<BR></TT></P>
2328
<H4><A name="Windows_nn8"></A>3.2.1.3 Perl</H4>
2329
<P><B> <TT>PERL5_INCLUDE</TT></B> : Set this to the directory containing
2330
perl.h
2331
<BR><B> <TT>PERL5_LIB</TT></B> : Set this to the Perl library including
2332
path for linking</P>
2333
<P> Example using nsPerl 5.004_04:</P>
2334
<P> <TT>PERL5_INCLUDE: D:\nsPerl5.004_04\lib\CORE
2335
<BR> PERL5_LIB: D:\nsPerl5.004_04\lib\CORE\perl.lib
2336
<BR></TT></P>
2337
<H4><A name="Windows_nn9"></A>3.2.1.4 Java</H4>
2338
<P><B> <TT>JAVA_INCLUDE</TT></B> : Set this to the directory containing
2339
jni.h
2340
<BR><B> <TT>JAVA_BIN</TT></B> : Set this to the bin directory containing
2341
javac.exe</P>
2342
<P> Example using JDK1.3:
2343
<BR> <TT>JAVA_INCLUDE: d:\jdk1.3\include
2344
<BR> JAVA_BIN: d:\jdk1.3\bin
2345
<BR></TT></P>
2346
<H4><A name="Windows_nn10"></A>3.2.1.5 Ruby</H4>
2432
<BR> <TT>TCL_INCLUDE: D:\tcl\include
2433
<BR> TCL_LIB: D:\tcl\lib\tcl83.lib
2434
<BR></TT></P>
2435
<H4><A name="Windows_r"></A>3.2.1.6 R</H4>
2436
<P><B> <TT>R_INCLUDE</TT></B> : Set this to the directory containing R.h
2437
<BR><B> <TT>R_LIB</TT></B> : Set this to the R library (Rdll.lib)
2438
including path for linking. The library needs to be built as described
2439
in the R README.packages file (the pexports.exe approach is the
2440
easiest).</P>
2441
<P> Example using R 2.5.1:
2442
<BR> <TT>R_INCLUDE: C:\Program Files\R\R-2.5.1\include
2443
<BR> R_LIB: C:\Program Files\R\R-2.5.1\bin\Rdll.lib
2444
<BR></TT></P>
2445
<H4><A name="Windows_ruby"></A>3.2.1.7 Ruby</H4>
2347
2446
<P><B> <TT>RUBY_INCLUDE</TT></B> : Set this to the directory containing
2348
2447
ruby.h
2349
2448
<BR><B> <TT>RUBY_LIB</TT></B> : Set this to the ruby library including
2352
2451
<BR> <TT>RUBY_INCLUDE: D:\ruby\lib\ruby\1.6\i586-mswin32
2353
2452
<BR> RUBY_LIB: D:\ruby\lib\mswin32-ruby16.lib
2354
2453
<BR></TT></P>
2355
<H4><A name="Windows_nn11"></A>3.2.1.6 C#</H4>
2356
<P> The C# examples do not require any environment variables to be set
2357
as a C# project file is included. Just open up the .sln solution file
2358
in Visual Studio .NET 2003 and do a Rebuild All from the Build menu.
2359
The accompanying C# and C++ project file are automatically used by the
2360
solution file.</P>
2361
<H3><A name="Windows_nn12"></A>3.2.2 Instructions for using the Examples
2362
with other compilers</H3>
2454
<H3><A name="Windows_other_compilers"></A>3.2.2 Instructions for using
2455
the Examples with other compilers</H3>
2363
2456
<P> If you do not have access to Visual C++ you will have to set up
2364
2457
project files / Makefiles for your chosen compiler. There is a section
2365
2458
in each of the language modules detailing what needs setting up using
2366
2459
Visual C++ which may be of some guidance. Alternatively you may want to
2367
2460
use Cygwin as described in the following section.</P>
2368
<H2><A name="Windows_nn13"></A>3.3 SWIG on Cygwin and MinGW</H2>
2461
<H2><A name="Windows_cygwin_mingw"></A>3.3 SWIG on Cygwin and MinGW</H2>
2369
2462
<P> SWIG can also be compiled and run using <A href="http://www.cygwin.com">
2370
2463
Cygwin</A> or <A href="http://www.mingw.org">MinGW</A> which provides a
2371
2464
Unix like front end to Windows and comes free with gcc, an ANSI C/C++
2372
2465
compiler. However, this is not a recommended approach as the prebuilt
2373
2466
executable is supplied.</P>
2374
<H3><A name="swig_exe"></A>3.3.1 Building swig.exe on Windows</H3>
2467
<H3><A name="Windows_swig_exe"></A>3.3.1 Building swig.exe on Windows</H3>
2375
2468
<P> If you want to replicate the build of swig.exe that comes with the
2376
2469
download, follow the MinGW instructions below. This is not necessary to
2377
2470
use the supplied swig.exe. This information is provided for those that
2387
2480
root directory to build swig.exe from the MinGW command prompt.</LI>
2388
2481
</UL>
2389
2482
<P> The step by step instructions to download and install MinGW and
2390
MSYS, then download and build the latest version of SWIG from cvs
2391
follow... Note that the instructions for obtaining SWIG from CVS are
2392
also online at <A href="http://www.swig.org/cvs.html">SWIG CVS</A>.</P>
2483
MSYS, then download and build the latest version of SWIG from SVN
2484
follow... Note that the instructions for obtaining SWIG from SVN are
2485
also online at <A href="http://www.swig.org/svn.html">SWIG SVN</A>.</P>
2393
2486
<P><B> Pitfall note:</B> Execute the steps in the order shown and don't
2394
2487
use spaces in path names. In fact it is best to use the default
2395
2488
installation directories.</P>
2437
2530
tar -zxf bison-2.0-MSYS.tar.gz
2438
2531
</PRE>
2439
2532
</DIV></LI>
2440
<LI> To get the latest SWIG CVS, type in the following:<DIV class="shell">
2533
<LI> To get the latest SWIG SVN (version from Subversion source
2534
control), type in the following:<DIV class="shell">
2441
2535
<PRE>
2442
2536
mkdir /usr/src
2443
2537
cd /usr/src
2444
export CVSROOT=:pserver:anonymous@swig.cvs.sourceforge.net:/cvsroot/swig
2445
cvs login
2446
(Logging in to anonymous@swig.cvs.sourceforge.net)
2447
CVS password: <Just Press Return Here>
2448
cvs -z3 checkout SWIG
2538
svn co https://swig.svn.sourceforge.net/svnroot/swig/trunk swig
2449
2539
</PRE>
2450
2540
</DIV><B> Pitfall note:</B> If you want to check out SWIG to a different
2451
folder to the proposed /usr/src/SWIG, do not use MSYS emulated windows
2541
folder to the proposed /usr/src/swig, do not use MSYS emulated windows
2452
2542
drive letters, because the autotools will fail miserably on those.</LI>
2453
2543
<LI> You are now ready to build SWIG. Execute the following commands to
2454
2544
build swig.exe:<DIV class="shell">
2455
2545
<PRE>
2456
cd /usr/src/SWIG
2546
cd /usr/src/swig
2457
2547
./autogen.sh
2458
2548
./configure
2459
2549
make
2460
2550
</PRE>
2461
2551
</DIV></LI>
2462
2552
</OL>
2463
<H4><A name="Windows_nn16"></A>3.3.1.2 Building swig.exe using Cygwin</H4>
2553
<H4><A name="Windows_cygwin"></A>3.3.1.2 Building swig.exe using Cygwin</H4>
2464
2554
<P> Note that SWIG can also be built using Cygwin. However, SWIG will
2465
2555
then require the Cygwin DLL when executing. Follow the Unix
2466
2556
instructions in the README file in the SWIG root directory. Note that
2468
2558
generated files which are supplied with the release distribution. These
2469
2559
files are generated using the <TT>autogen.sh</TT> script and will only
2470
2560
need regenerating in circumstances such as changing the build system.</P>
2471
<H4><A name="Windows_nn17"></A>3.3.1.3 Building swig.exe alternatives</H4>
2561
<H4><A name="Windows_building_alternatives"></A>3.3.1.3 Building
2562
swig.exe alternatives</H4>
2472
2563
<P> If you don't want to install Cygwin or MinGW, use a different
2473
2564
compiler to build SWIG. For example, all the source code files can be
2474
2565
added to a Visual C++ project file in order to build swig.exe from the
2475
2566
Visual C++ IDE.</P>
2476
<H3><A name="examples_cygwin"></A>3.3.2 Running the examples on Windows
2477
using Cygwin</H3>
2567
<H3><A name="Windows_examples_cygwin"></A>3.3.2 Running the examples on
2568
Windows using Cygwin</H3>
2478
2569
<P> The examples and test-suite work as successfully on Cygwin as on any
2479
2570
other Unix operating system. The modules which are known to work are
2480
2571
Python, Tcl, Perl, Ruby, Java and C#. Follow the Unix instructions in
2905
2996
<LI><A href="#SWIG_nn25">Linking to <TT>char *</TT></A></LI>
2906
2997
<LI><A href="#SWIG_nn26">Arrays</A></LI>
2907
2998
<LI><A href="#SWIG_readonly_variables">Creating read-only variables</A></LI>
2908
<LI><A href="#SWIG_nn28">Renaming and ignoring declarations</A></LI>
2999
<LI><A href="#SWIG_rename_ignore">Renaming and ignoring declarations</A></LI>
2909
3000
<LI><A href="#SWIG_default_args">Default/optional arguments</A></LI>
2910
3001
<LI><A href="#SWIG_nn30">Pointers to functions and callbacks</A></LI>
2911
3002
</UL>
2976
3067
-mzscheme Generate Mzscheme wrappers
2977
3068
-ocaml Generate Ocaml wrappers
2978
3069
-perl Generate Perl wrappers
2979
-php Generate PHP wrappers
3070
-php4 Generate PHP4 wrappers
3071
-php5 Generate PHP5 wrappers
2980
3072
-pike Generate Pike wrappers
2981
3073
-python Generate Python wrappers
3074
-r Generate R (aka GNU S) wrappers
2982
3075
-ruby Generate Ruby wrappers
2983
3076
-sexp Generate Lisp S-Expressions wrappers
2984
3077
-tcl Generate Tcl wrappers
4104
4197
Although these directives still work, they generate a warning message.
4105
4198
Simply change the directives to <TT>%immutable;</TT> and <TT>%mutable;</TT>
4106
4199
to silence the warning. Don't forget the extra semicolon!</P>
4107
<H3><A name="SWIG_nn28"></A>5.4.7 Renaming and ignoring declarations</H3>
4200
<H3><A name="SWIG_rename_ignore"></A>5.4.7 Renaming and ignoring
4201
declarations</H3>
4108
4202
<P> Normally, the name of a C declaration is used when that declaration
4109
4203
is wrapped into the target language. However, this may generate a
4110
4204
conflict with a keyword or already existing function in the scripting
4290
4384
int binary_op(int a, int b, int (*op)(int,int));
4291
4385
4292
4386
/* Some callback functions */
4293
%callback("%s_cb")
4387
%callback("%s_cb");
4294
4388
int add(int,int);
4295
4389
int sub(int,int);
4296
4390
int mul(int,int);
4297
%nocallback
4391
%nocallback;
4298
4392
</PRE>
4299
4393
</DIV>
4300
4394
<P> The argument to <TT>%callback</TT> is a printf-style format string
4324
4418
<DIV class="code">
4325
4419
<PRE>
4326
4420
/* Some callback functions */
4327
%callback("%(upper)s")
4421
%callback("%(upper)s");
4328
4422
int add(int,int);
4329
4423
int sub(int,int);
4330
4424
int mul(int,int);
4331
%nocallback
4425
%nocallback;
4332
4426
</PRE>
4333
4427
</DIV>
4334
4428
<P> A format string of <TT>"%(lower)s"</TT> converts all characters to
5259
5353
</UL>
5260
5354
</LI>
5261
5355
<LI><A href="#SWIGPlus_nn28">Wrapping overloaded operators</A></LI>
5262
<LI><A href="#SWIGPlus_nn29">Class extension</A></LI>
5356
<LI><A href="#SWIGPlus_class_extension">Class extension</A></LI>
5263
5357
<LI><A href="#SWIGPlus_nn30">Templates</A></LI>
5264
5358
<LI><A href="#SWIGPlus_nn31">Namespaces</A></LI>
5359
<LI><A href="#SWIGPlus_renaming_templated_types_namespaces">Renaming
5360
templated types in namespaces</A></LI>
5265
5361
<LI><A href="#SWIGPlus_exception_specifications">Exception
5266
5362
specifications</A></LI>
5267
5363
<LI><A href="#SWIGPlus_catches">Exception handling with %catches</A></LI>
5659
5755
<LI>Default constructors are not generated for classes with pure virtual
5660
5756
methods or for classes that inherit from an abstract class, but don't
5661
5757
provide definitions for all of the pure methods.</LI>
5662
<LI>A default constructor is not created unless all bases classes
5663
support a default constructor.</LI>
5758
<LI>A default constructor is not created unless all base classes support
5759
a default constructor.</LI>
5664
5760
<LI>Default constructors and implicit destructors are not created if a
5665
5761
class defines them in a <TT>private</TT> or <TT>protected</TT> section.</LI>
5666
5762
<LI>Default constructors and implicit destructors are not created if any
6344
6440
in functions of a base class. The type-checker properly casts pointer
6345
6441
values and is safe to use with multiple inheritance.</P>
6346
6442
<P> SWIG treats private or protected inheritance as close to the C++
6347
spirit, and target language capabilities, as possible. In most of the
6348
cases, this means that SWIG will parse the non-public inheritance
6443
spirit, and target language capabilities, as possible. In most cases,
6444
this means that SWIG will parse the non-public inheritance
6349
6445
declarations, but that will have no effect in the generated code,
6350
6446
besides the implicit policies derived for constructor and destructors.</P>
6351
6447
<P> The following example shows how SWIG handles inheritance. For
7069
7165
</PRE>
7070
7166
</DIV></LI>
7071
7167
<LI>
7168
<P> Currently no resolution is performed in order to match function
7169
parameters. This means function parameter types must match exactly. For
7170
example, namespace qualifiers and typedefs will not work. The following
7171
usage of typedefs demonstrates this:<DIV class="code">
7172
<PRE>
7173
typedef int Integer;
7174
7175
%rename(foo_i) foo(int);
7176
7177
class Spam {
7178
public:
7179
void foo(Integer); // Stays 'foo' (not renamed)
7180
};
7181
class Ham {
7182
public:
7183
void foo(int); // Renamed to foo_i
7184
};
7185
</PRE>
7186
</DIV></P>
7187
</LI>
7188
<LI>
7072
7189
<P> The name matching rules also use default arguments for finer control
7073
7190
when wrapping methods that have default arguments. Recall that methods
7074
7191
with default arguments are wrapped as if the equivalent overloaded
7271
7388
<LI>The semantics of certain C++ operators may not match those in the
7272
7389
target language.</LI>
7273
7390
</UL>
7274
<H2><A name="SWIGPlus_nn29"></A>6.17 Class extension</H2>
7391
<H2><A name="SWIGPlus_class_extension"></A>6.17 Class extension</H2>
7275
7392
<P> New methods can be added to a class using the <TT>%extend</TT>
7276
7393
directive. This directive is primarily used in conjunction with proxy
7277
7394
classes to add additional functionality to an existing class. For
7319
7436
<P> The C++ 'this' pointer is often needed to access member variables,
7320
7437
methods etc. The <TT>$self</TT> special variable should be used
7321
7438
wherever you could use 'this'. The example above demonstrates this for
7322
accessing member variables. The implicit 'this' pointer that is present
7323
in C++ methods is not present in <TT>%extend</TT> methods. In order to
7324
access anything in the extended class or its base class, an explicit
7325
'this' is required. The following example shows how one could access
7326
base class members:</P>
7439
accessing member variables. Note that the members dereferenced by <TT>
7440
$self</TT> must be public members as the code is ultimately generated
7441
into a global function and so will not have any access to non-public
7442
members. The implicit 'this' pointer that is present in C++ methods is
7443
not present in <TT>%extend</TT> methods. In order to access anything in
7444
the extended class or its base class, an explicit 'this' is required.
7445
The following example shows how one could access base class members:</P>
7327
7446
<DIV class="code">
7328
7447
<PRE>
7329
7448
struct Base {
7336
7455
};
7337
7456
%extend Derived {
7338
7457
virtual void method(int v) {
7339
$self->Base::method(v);
7340
$self->value = v;
7458
$self->Base::method(v); // akin to this->Base::method(v);
7459
$self->value = v; // akin to this->value = v;
7341
7460
...
7342
7461
}
7343
7462
}
7359
7478
void bar(list<int,100> *x);
7360
7479
</PRE>
7361
7480
</DIV>
7362
<P> There are some restrictions on the use of non-type arguments.
7363
Specifically, they have to be simple literals and not expressions. For
7364
example:</P>
7481
<P> There are some restrictions on the use of non-type arguments. Simple
7482
literals are supported, and so are some constant expressions. However,
7483
use of '<' and '>' within a constant expressions currently is not
7484
supported by SWIG ('<=' and '>=' are though). For example:</P>
7365
7485
<DIV class="code">
7366
7486
<PRE>
7367
void bar(list<int,100> *x); // OK
7368
void bar(list<int,2*50> *x); // Illegal
7487
void bar(list<int,100> *x); // OK
7488
void bar(list<int,2*50> *x); // OK
7489
void bar(list<int,(2>1 ? 100 : 50)> *x) // Not supported
7369
7490
</PRE>
7370
7491
</DIV>
7371
7492
<P> The type system is smart enough to figure out clever games you might
7609
7730
</PRE>
7610
7731
</DIV>
7611
7732
<P> Note the use of a vararg macro for the type T. If this wasn't used,
7612
the comma in the templated type in last example would not be possible.</P>
7733
the comma in the templated type in the last example would not be
7734
possible.</P>
7613
7735
<P> The SWIG template mechanism<EM> does</EM> support specialization.
7614
7736
For instance, if you define a class like this,</P>
7615
7737
<DIV class="code">
7869
7991
7870
7992
...
7871
7993
template<class T> class List {
7872
...
7873
public:
7874
List() { };
7875
...
7994
...
7995
public:
7996
List() { };
7997
T get(int index);
7998
...
7876
7999
};
7877
8000
</PRE>
7878
8001
</DIV>
8243
8366
conventions as used in the input file. Thus, if there are no symbol
8244
8367
conflicts in the input, there will be no conflicts in the generated
8245
8368
code.</P>
8246
<P><B> Note:</B> Namespaces have a subtle effect on the wrapping of
8247
conversion operators. For instance, suppose you had an interface like
8248
this:</P>
8369
<P><B> Note:</B> In the same way that no resolution is performed on
8370
parameters, a conversion operator name must match exactly to how it is
8371
defined. Do not change the qualification of the operator. For example,
8372
suppose you had an interface like this:</P>
8249
8373
<DIV class="code">
8250
8374
<PRE>
8251
8375
namespace foo {
8259
8383
}
8260
8384
</PRE>
8261
8385
</DIV>
8262
<P> To wrap the conversion function, you might be inclined to write
8263
this:</P>
8386
<P> The following is how the feature is expected to be written for a
8387
successful match:</P>
8264
8388
<DIV class="code">
8265
8389
<PRE>
8266
8390
%rename(tofoo) foo::spam::operator bar();
8267
8391
</PRE>
8268
8392
</DIV>
8269
<P> The only problem is that it doesn't work. The reason it doesn't work
8270
is that <TT>bar</TT> is not defined in the global scope. Therefore, to
8271
make it work, do this instead:</P>
8393
<P> The following does not work as no namespace resolution is performed
8394
in the matching of conversion operator names:</P>
8272
8395
<DIV class="code">
8273
8396
<PRE>
8274
8397
%rename(tofoo) foo::spam::operator <B>foo::</B>bar();
8275
8398
</PRE>
8276
8399
</DIV>
8400
<P> Note, however, that if the operator is defined using a qualifier in
8401
its name, then the feature must use it too...</P>
8402
<DIV class="code">
8403
<PRE>
8404
%rename(tofoo) foo::spam::operator bar(); // will not match
8405
%rename(tofoo) foo::spam::operator foo::bar(); // will match
8406
namespace foo {
8407
class bar;
8408
class spam {
8409
public:
8410
...
8411
operator foo::bar();
8412
...
8413
};
8414
}
8415
</PRE>
8416
</DIV>
8417
<P><B> Compatibility Note:</B> Versions of SWIG prior to 1.3.32 were
8418
inconsistent in this approach. A fully qualified name was usually
8419
required, but would not work in some situations.</P>
8277
8420
<P><B> Note:</B> The flattening of namespaces is only intended to serve
8278
as a basic namespace implementation. Since namespaces are a new
8279
addition to SWIG, none of the target language modules are currently
8280
programmed with any namespace awareness. In the future, language
8281
modules may or may not provide more advanced namespace support.</P>
8282
<H2><A name="SWIGPlus_exception_specifications"></A>6.20 Exception
8421
as a basic namespace implementation. None of the target language
8422
modules are currently programmed with any namespace awareness. In the
8423
future, language modules may or may not provide more advanced namespace
8424
support.</P>
8425
<H2><A name="SWIGPlus_renaming_templated_types_namespaces"></A>6.20
8426
Renaming templated types in namespaces</H2>
8427
<P> As has been mentioned, when %rename includes parameters, the
8428
parameter types must match exactly (no typedef or namespace resolution
8429
is performed). SWIG treats templated types slightly differently and has
8430
an additional matching rule so unlike non-templated types, an exact
8431
match is not always required. If the fully qualified templated type is
8432
specified, it will have a higher precedence over the generic template
8433
type. In the example below, the generic template type is used to rename
8434
to <TT>bbb</TT> and the fully qualified type is used to rename to <TT>
8435
ccc</TT>.</P>
8436
<DIV class="code">
8437
<PRE>
8438
%rename(bbb) Space::ABC::aaa(T t); // will match but with lower precedence than ccc
8439
%rename(ccc) Space::ABC<Space::XYZ>::aaa(Space::XYZ t); // will match but with higher precedence than bbb
8440
8441
namespace Space {
8442
class XYZ {};
8443
template<typename T> struct ABC {
8444
void aaa(T t) {}
8445
};
8446
}
8447
%template(ABCXYZ) Space::ABC<Space::XYZ>;
8448
</PRE>
8449
</DIV>
8450
<P> It should now be apparent that there are many ways to achieve a
8451
renaming with %rename. This is demonstrated by the following two
8452
examples, which are effectively the same as the above example. Below
8453
shows how %rename can be placed inside a namespace.</P>
8454
<DIV class="code">
8455
<PRE>
8456
namespace Space {
8457
%rename(bbb) ABC::aaa(T t); // will match but with lower precedence than ccc
8458
%rename(ccc) ABC<Space::XYZ>::aaa(Space::XYZ t); // will match but with higher precedence than bbb
8459
%rename(ddd) ABC<Space::XYZ>::aaa(XYZ t); // will not match
8460
}
8461
8462
namespace Space {
8463
class XYZ {};
8464
template<typename T> struct ABC {
8465
void aaa(T t) {}
8466
};
8467
}
8468
%template(ABCXYZ) Space::ABC<Space::XYZ>;
8469
</PRE>
8470
</DIV>
8471
<P> Note that <TT>ddd</TT> does not match as there is no namespace
8472
resolution for parameter types and the fully qualified type must be
8473
specified for template type expansion. The following example shows how
8474
%rename can be placed within %extend.</P>
8475
<DIV class="code">
8476
<PRE>
8477
namespace Space {
8478
%extend ABC {
8479
%rename(bbb) aaa(T t); // will match but with lower precedence than ccc
8480
}
8481
%extend ABC<Space::XYZ> {
8482
%rename(ccc) aaa(Space::XYZ t); // will match but with higher precedence than bbb
8483
%rename(ddd) aaa(XYZ t); // will not match
8484
}
8485
}
8486
8487
namespace Space {
8488
class XYZ {};
8489
template<typename T> struct ABC {
8490
void aaa(T t) {}
8491
};
8492
}
8493
%template(ABCXYZ) Space::ABC<Space::XYZ>;
8494
</PRE>
8495
</DIV>
8496
<H2><A name="SWIGPlus_exception_specifications"></A>6.21 Exception
8283
8497
specifications</H2>
8284
8498
<P> When C++ programs utilize exceptions, exceptional behavior is
8285
8499
sometimes specified as part of a function or method declaration. For
8320
8534
"<A href="#exception">Exception handling with %exception</A>" section
8321
8535
for details. The next section details a way of simulating an exception
8322
8536
specification or replacing an existing one.</P>
8323
<H2><A name="SWIGPlus_catches"></A>6.21 Exception handling with %catches</H2>
8537
<H2><A name="SWIGPlus_catches"></A>6.22 Exception handling with %catches</H2>
8324
8538
<P> Exceptions are automatically handled for methods with an exception
8325
8539
specification. Similar handling can be achieved for methods without
8326
8540
exception specifications through the <TT>%catches</TT> feature. It is
8365
8579
single catch handler for the base class, <TT>EBase</TT> will be
8366
8580
generated to convert the C++ exception into a target language
8367
8581
error/exception.</P>
8368
<H2><A name="SWIGPlus_nn33"></A>6.22 Pointers to Members</H2>
8582
<H2><A name="SWIGPlus_nn33"></A>6.23 Pointers to Members</H2>
8369
8583
<P> Starting with SWIG-1.3.7, there is limited parsing support for
8370
8584
pointers to C++ class members. For example:</P>
8371
8585
<DIV class="code">
8396
8610
with member pointers. Normally SWIG tries to keep track of inheritance
8397
8611
when checking types. However, no such support is currently provided for
8398
8612
member pointers.</P>
8399
<H2><A name="SWIGPlus_nn34"></A>6.23 Smart pointers and operator->()</H2>
8613
<H2><A name="SWIGPlus_nn34"></A>6.24 Smart pointers and operator->()</H2>
8400
8614
<P> In some C++ programs, objects are often encapsulated by
8401
8615
smart-pointers or proxy classes. This is sometimes done to implement
8402
8616
automatic memory management (reference counting) or persistence.
8558
8772
</PRE>
8559
8773
</DIV>
8560
8774
<P><B> Note:</B> Smart pointer support was first added in SWIG-1.3.14.</P>
8561
<H2><A name="SWIGPlus_nn35"></A>6.24 Using declarations and inheritance</H2>
8775
<H2><A name="SWIGPlus_nn35"></A>6.25 Using declarations and inheritance</H2>
8562
8776
<P> <TT>using</TT> declarations are sometimes used to adjust access to
8563
8777
members of base classes. For example:</P>
8564
8778
<DIV class="code">
8692
8906
</PRE>
8693
8907
</DIV></LI>
8694
8908
</UL>
8695
<H2><A name="SWIGPlus_nested_classes"></A>6.25 Nested classes</H2>
8909
<H2><A name="SWIGPlus_nested_classes"></A>6.26 Nested classes</H2>
8696
8910
<P> There is limited support for nested structs and unions when wrapping
8697
8911
C code, see <A href="#SWIG_nested_structs">Nested structures</A> for
8698
8912
further details. However, there is no nested class/struct/union support
8773
8987
<P> The downside to this approach is having to maintain two definitions
8774
8988
of <TT>Inner</TT>, the real one and the one in the interface file that
8775
8989
SWIG parses.</P>
8776
<H2><A name="SWIGPlus_nn37"></A>6.26 A brief rant about
8990
<H2><A name="SWIGPlus_nn37"></A>6.27 A brief rant about
8777
8991
const-correctness</H2>
8778
8992
<P> A common issue when working with C++ programs is dealing with all
8779
8993
possible ways in which the <TT>const</TT> qualifier (or lack thereof)
8813
9027
a problem for most SWIG projects. Of course, you might want to consider
8814
9028
using another tool if maintaining constness is the most important part
8815
9029
of your project.</P>
8816
<H2><A name="SWIGPlus_nn42"></A>6.27 Where to go for more information</H2>
9030
<H2><A name="SWIGPlus_nn42"></A>6.28 Where to go for more information</H2>
8817
9031
<P> If you're wrapping serious C++ code, you might want to pick up a
8818
9032
copy of "The Annotated C++ Reference Manual" by Ellis and Stroustrup.
8819
9033
This is the reference document we use to guide a lot of SWIG's C++
8840
9054
<LI><A href="#Preprocessor_nn5">Macro Expansion</A></LI>
8841
9055
<LI><A href="#Preprocessor_nn6">SWIG Macros</A></LI>
8842
9056
<LI><A href="#Preprocessor_nn7">C99 and GNU Extensions</A></LI>
8843
<LI><A href="#Preprocessor_nn8">Preprocessing and %{ ... %} blocks</A></LI>
8844
<LI><A href="#Preprocessor_nn9">Preprocessing and { ... }</A></LI>
9057
<LI><A href="#Preprocessor_nn8">Preprocessing and %{ ... %} & " ... "
9058
delimiters</A></LI>
9059
<LI><A href="#Preprocessor_nn9">Preprocessing and { ... } delimiters</A></LI>
9060
<LI><A href="#Preprocessor_typemap_delimiters">Preprocessor and Typemaps</A>
9061
</LI>
8845
9062
<LI><A href="#Preprocessor_nn10">Viewing preprocessor output</A></LI>
8846
9063
<LI><A href="#Preprocessor_warning_error">The #error and #warning
8847
9064
directives</A></LI>
9051
9268
useful to interface building. However, they are used internally to
9052
9269
implement a number of SWIG directives and are provided to make SWIG
9053
9270
more compatible with C99 code.</P>
9054
<H2><A name="Preprocessor_nn8"></A>7.7 Preprocessing and %{ ... %}
9055
blocks</H2>
9271
<H2><A name="Preprocessor_nn8"></A>7.7 Preprocessing and %{ ... %} & "
9272
... " delimiters</H2>
9056
9273
<P> The SWIG preprocessor does not process any text enclosed in a code
9057
9274
block %{ ... %}. Therefore, if you write code like this,</P>
9058
9275
<DIV class="code">
9068
9285
</DIV>
9069
9286
<P> the contents of the <TT>%{ ... %}</TT> block are copied without
9070
9287
modification to the output (including all preprocessor directives).</P>
9071
<H2><A name="Preprocessor_nn9"></A>7.8 Preprocessing and { ... }</H2>
9288
<H2><A name="Preprocessor_nn9"></A>7.8 Preprocessing and { ... }
9289
delimiters</H2>
9072
9290
<P> SWIG always runs the preprocessor on text appearing inside <TT>{ ...
9073
9291
}</TT>. However, sometimes it is desirable to make a preprocessor
9074
9292
directive pass through to the output file. For example:</P>
9099
9317
</DIV>
9100
9318
<P> SWIG will strip the extra <TT>%</TT> and leave the preprocessor
9101
9319
directive in the code.</P>
9102
<H2><A name="Preprocessor_nn10"></A>7.9 Viewing preprocessor output</H2>
9320
<H2><A name="Preprocessor_typemap_delimiters"></A>7.9 Preprocessor and
9321
Typemaps</H2>
9322
<P> <A href="Typemaps.html">Typemaps</A> support a special attribute
9323
where the { ... } delimiters can be used, but the delimiters are not
9324
actually generated into the code. The effect is then similar to using
9325
"" or %{ %} delimiters but the code<B> is</B> run through the
9326
preprocessor. For example:</P>
9327
<DIV class="code">
9328
<PRE>
9329
#define SWIG_macro(CAST) (CAST)$input
9330
%typemap(in) Int {$1= SWIG_macro(int);}
9331
</PRE>
9332
</DIV>
9333
<P> might generate</P>
9334
<DIV class="code">
9335
<PRE>
9336
{
9337
arg1=(int)jarg1;
9338
}
9339
</PRE>
9340
</DIV>
9341
<P> whereas</P>
9342
<DIV class="code">
9343
<PRE>
9344
#define SWIG_macro(CAST) (CAST)$input
9345
%typemap(in,noblock=1) Int {$1= SWIG_macro(int);}
9346
</PRE>
9347
</DIV>
9348
<P> might generate</P>
9349
<DIV class="code">
9350
<PRE>
9351
arg1=(int)jarg1;
9352
</PRE>
9353
</DIV>
9354
<P> and</P>
9355
<DIV class="code">
9356
<PRE>
9357
#define SWIG_macro(CAST) (CAST)$input
9358
%typemap(in) Int %{$1=SWIG_macro(int);%}
9359
</PRE>
9360
</DIV>
9361
<P> would generate</P>
9362
<DIV class="code">
9363
<PRE>
9364
arg1=SWIG_macro(int);
9365
</PRE>
9366
</DIV>
9367
<H2><A name="Preprocessor_nn10"></A>7.10 Viewing preprocessor output</H2>
9103
9368
<P> Like many compilers, SWIG supports a <TT>-E</TT> command line option
9104
9369
to display the output from the preprocessor. When the <TT>-E</TT>
9105
9370
switch is used, SWIG will not generate any wrappers. Instead the
9106
9371
results after the preprocessor has run are displayed. This might be
9107
9372
useful as an aid to debugging and viewing the results of macro
9108
9373
expansions.</P>
9109
<H2><A name="Preprocessor_warning_error"></A>7.10 The #error and
9374
<H2><A name="Preprocessor_warning_error"></A>7.11 The #error and
9110
9375
#warning directives</H2>
9111
9376
<P> SWIG supports the commonly used <TT>#warning</TT> and <TT>#error</TT>
9112
9377
preprocessor directives. The <TT>#warning</TT> directive will cause
10768
11033
<UL>
10769
11034
<LI><A href="#Typemaps_nn22">Scope</A></LI>
10770
11035
<LI><A href="#Typemaps_nn23">Declaring new local variables</A></LI>
10771
<LI><A href="#Typemaps_nn24">Special variables</A></LI>
11036
<LI><A href="#Typemaps_special_variables">Special variables</A></LI>
10772
11037
</UL>
10773
11038
</LI>
10774
11039
<LI><A href="#Typemaps_nn25">Common typemap methods</A>
11260
11525
typemaps. In addition, each type pattern can be parameterized with a
11261
11526
list of temporary variables (parms). The purpose of these variables
11262
11527
will be explained shortly.</P>
11263
<P><EM>code</EM> specifies the C code used in the typemap. It can take
11264
any one of the following forms:</P>
11528
<P><EM>code</EM> specifies the code used in the typemap. Usually this is
11529
C/C++ code, but in the strongly typed target languages, such as Java
11530
and C#, this can contain target language code for certain typemaps. It
11531
can take any one of the following forms:</P>
11265
11532
<DIV class="diagram">
11266
11533
<PRE>
11267
11534
code : { ... }
11269
11536
| %{ ... %}
11270
11537
</PRE>
11271
11538
</DIV>
11272
<P> Here are some examples of valid typemap specifications:</P>
11539
<P> Note that the preprocessor will expand code within the {}
11540
delimiters, but not in the last two styles of delimiters, see <A href="#Preprocessor_typemap_delimiters">
11541
Preprocessor and Typemaps</A>. Here are some examples of valid typemap
11542
specifications:</P>
11273
11543
<DIV class="code">
11274
11544
<PRE>
11275
11545
/* Simple typemap declarations */
11953
12223
<P> Some typemaps do not recognize local variables (or they may simply
11954
12224
not apply). At this time, only typemaps that apply to argument
11955
12225
conversion support this.</P>
11956
<H3><A name="Typemaps_nn24"></A>10.4.3 Special variables</H3>
12226
<H3><A name="Typemaps_special_variables"></A>10.4.3 Special variables</H3>
11957
12227
<P> Within all typemaps, the following special variables are expanded.</P>
11958
12228
<CENTER>
11959
12229
<TABLE border="1" summary="Typemap special variables">
12614
12884
<DIV class="code">
12615
12885
<PRE>
12616
12886
#if defined(SWIGPERL)
12887
%typemap(in) int "$1 = ($1_ltype) SvIV($input);"
12888
#elif defined(SWIGRUBY)
12617
12889
%typemap(in) int "$1 = NUM2INT($input);"
12618
#elif defined(SWIGRUBY)
12619
%typemap(in) int "$1 = ($1_ltype) SvIV($input);"
12620
12890
#else
12621
12891
#warning no "in" typemap defined
12622
12892
#endif
15311
15581
<UL>
15312
15582
<LI><A href="#Warnings_nn2">Introduction</A></LI>
15313
15583
<LI><A href="#Warnings_suppression">Warning message suppression</A></LI>
15314
<LI><A href="#Warnings_nn4">Enabling additional warnings</A></LI>
15584
<LI><A href="#Warnings_nn4">Enabling extra warnings</A></LI>
15315
15585
<LI><A href="#Warnings_nn5">Issuing a warning message</A></LI>
15586
<LI><A href="#Warnings_symbolic_symbols">Symbolic symbols</A></LI>
15316
15587
<LI><A href="#Warnings_nn6">Commentary</A></LI>
15317
15588
<LI><A href="#Warnings_nn7">Warnings as errors</A></LI>
15318
15589
<LI><A href="#Warnings_nn8">Message output format</A></LI>
15376
15647
</PRE>
15377
15648
</DIV>
15378
15649
<P> The <TT>%warnfilter</TT> directive has the same semantics as other
15379
declaration modifiers like <TT>%rename</TT>, <TT>%ignore</TT>, and <TT>
15380
%feature</TT>. For example, if you wanted to suppress a warning for a
15381
method in a class hierarchy, you could do this:</P>
15650
declaration modifiers like <TT>%rename</TT>, <TT>%ignore</TT> and <TT>
15651
%feature</TT>, see the <A href="#features">%feature directive</A>
15652
section. For example, if you wanted to suppress a warning for a method
15653
in a class hierarchy, you could do this:</P>
15382
15654
<DIV class="code">
15383
15655
<PRE>
15384
15656
%warnfilter(501) Object::foo;
15413
15685
warning messages are there for a reason---to tell you that something
15414
15686
may be<EM> broken</EM> in your interface. Ignore the warning messages
15415
15687
at your own peril.</P>
15416
<H2><A name="Warnings_nn4"></A>14.3 Enabling additional warnings</H2>
15688
<H2><A name="Warnings_nn4"></A>14.3 Enabling extra warnings</H2>
15417
15689
<P> Some warning messages are disabled by default and are generated only
15418
to provide additional diagnostics. All warning messages can be enabled
15419
using the <TT>-Wall</TT> option. For example:</P>
15690
to provide additional diagnostics. These warnings can be turned on
15691
using the <TT>-Wextra</TT> option. For example:</P>
15420
15692
<DIV class="shell">
15421
15693
<PRE>
15422
% swig -Wall -python example.i
15694
% swig -Wextra -python example.i
15423
15695
</PRE>
15424
15696
</DIV>
15425
<P> When <TT>-Wall</TT> is used, all other warning filters are disabled.</P>
15426
15697
<P> To selectively turn on extra warning messages, you can use the
15427
15698
directives and options in the previous section--simply add a "+" to all
15428
15699
warning numbers. For example:</P>
15431
15702
% swig -w+309,+452 example.i
15432
15703
</PRE>
15433
15704
</DIV>
15434
<P> or</P>
15705
<P> or in your interface file use either</P>
15435
15706
<DIV class="code">
15436
15707
<PRE>
15437
15708
#pragma SWIG nowarn=+309,+452
15446
15717
<P> Note: selective enabling of warnings with <TT>%warnfilter</TT>
15447
15718
overrides any global settings you might have made using <TT>-w</TT> or <TT>
15448
15719
#pragma</TT>.</P>
15720
<P> You can of course also enable all warnings and suppress a select
15721
few, for example:</P>
15722
<DIV class="shell">
15723
<PRE>
15724
% swig -Wextra -w309,452 example.i
15725
</PRE>
15726
</DIV>
15727
<P> The warnings on the right take precedence over the warnings on the
15728
left, so in the above example <TT>-Wextra</TT> adds numerous warnings
15729
including 452, but then <TT>-w309,452</TT> overrides this and so 452 is
15730
suppressesed.</P>
15731
<P> If you would like all warnings to appear, regardless of the warning
15732
filters used, then use the <TT>-Wall</TT> option. The <TT>-Wall</TT>
15733
option also turns on the extra warnings that <TT>-Wextra</TT> adds,
15734
however, it is subtely different. When <TT>-Wall</TT> is used, it also
15735
disables all other warning filters, that is, any warnings suppressed or
15736
added in <TT>%warnfilter</TT>, <TT>#pragma SWIG nowarn</TT> or the <TT>
15737
-w</TT> option.</P>
15449
15738
<H2><A name="Warnings_nn5"></A>14.4 Issuing a warning message</H2>
15450
15739
<P> Warning messages can be issued from an interface file using a number
15451
15740
of directives. The <TT>%warn</TT> directive is the most simple:</P>
15452
15741
<DIV class="code">
15453
15742
<PRE>
15454
%warn "750:This is your last warning!"
15743
%warn "900:This is your last warning!"
15455
15744
</PRE>
15456
15745
</DIV>
15457
15746
<P> All warning messages are optionally prefixed by the warning number
15469
15758
warning</TT> attribute of a typemap declaration. For example:</P>
15470
15759
<DIV class="code">
15471
15760
<PRE>
15472
%typemap(in, warning="751:You are really going to regret this") blah * {
15761
%typemap(in, warning="901:You are really going to regret this") blah * {
15473
15762
...
15474
15763
}
15475
15764
</PRE>
15476
15765
</DIV>
15477
15766
<P> In this case, the warning message will be printed whenever the
15478
15767
typemap is actually used.</P>
15479
<H2><A name="Warnings_nn6"></A>14.5 Commentary</H2>
15768
<H2><A name="Warnings_symbolic_symbols"></A>14.5 Symbolic symbols</H2>
15769
<P> The <TT>swigwarn.swg</TT> file that is installed with SWIG contains
15770
symbol constants that could also be used in <TT>%warnfilter</TT> and <TT>
15771
#pragma SWIG nowarn</TT>. For example this file contains the following
15772
line:</P>
15773
<DIV class="code">
15774
<PRE>
15775
%define SWIGWARN_TYPE_UNDEFINED_CLASS 401 %enddef
15776
</PRE>
15777
</DIV>
15778
<P> so <TT>SWIGWARN_TYPE_UNDEFINED_CLASS</TT> could be used instead of
15779
401, for example:</P>
15780
<DIV class="code">
15781
<PRE>
15782
#pragma SWIG nowarn=SWIGWARN_TYPE_UNDEFINED_CLASS
15783
</PRE>
15784
</DIV>
15785
<P> or</P>
15786
<DIV class="code">
15787
<PRE>
15788
%warnfilter(SWIGWARN_TYPE_UNDEFINED_CLASS) Foo;
15789
</PRE>
15790
</DIV>
15791
<H2><A name="Warnings_nn6"></A>14.6 Commentary</H2>
15480
15792
<P> The ability to suppress warning messages is really only provided for
15481
advanced users and is not recommended in normal use. There are no plans
15482
to provide symbolic names or options that identify specific types or
15483
groups of warning messages---the numbers must be used explicitly.</P>
15793
advanced users and is not recommended in normal use. You are advised to
15794
modify your interface to fix the problems highlighted by the warnings
15795
wherever possible instead of suppressing warnings.</P>
15484
15796
<P> Certain types of SWIG problems are errors. These usually arise due
15485
15797
to parsing errors (bad syntax) or semantic problems for which there is
15486
15798
no obvious recovery. There is no mechanism for suppressing error
15487
15799
messages.</P>
15488
<H2><A name="Warnings_nn7"></A>14.6 Warnings as errors</H2>
15800
<H2><A name="Warnings_nn7"></A>14.7 Warnings as errors</H2>
15489
15801
<P> Warnings can be handled as errors by using the <TT>-Werror</TT>
15490
15802
command line option. This will cause SWIG to exit with a non successful
15491
15803
exit code if a warning is encountered.</P>
15492
<H2><A name="Warnings_nn8"></A>14.7 Message output format</H2>
15804
<H2><A name="Warnings_nn8"></A>14.8 Message output format</H2>
15493
15805
<P> The output format for both warnings and errors can be selected for
15494
15806
integration with your favourite IDE/editor. Editors and IDEs can
15495
15807
usually parse error messages and if in the appropriate format will
15505
15817
example.i(4): Syntax error in input.
15506
15818
</PRE>
15507
15819
</DIV>
15508
<H2><A name="Warnings_nn9"></A>14.8 Warning number reference</H2>
15509
<H3><A name="Warnings_nn10"></A>14.8.1 Deprecated features (100-199)</H3>
15820
<H2><A name="Warnings_nn9"></A>14.9 Warning number reference</H2>
15821
<H3><A name="Warnings_nn10"></A>14.9.1 Deprecated features (100-199)</H3>
15510
15822
<UL>
15511
15823
<LI>101. Deprecated <TT>%extern</TT> directive.</LI>
15512
15824
<LI>102. Deprecated <TT>%val</TT> directive.</LI>
15530
15842
<LI>120. Deprecated command line option (-c).</LI>
15531
15843
<LI>121. Deprecated <TT>%name</TT> directive.</LI>
15532
15844
</UL>
15533
<H3><A name="Warnings_nn11"></A>14.8.2 Preprocessor (200-299)</H3>
15845
<H3><A name="Warnings_nn11"></A>14.9.2 Preprocessor (200-299)</H3>
15534
15846
<UL>
15535
15847
<LI>201. Unable to find 'filename'.</LI>
15536
15848
<LI>202. Could not evaluate 'expr'.</LI>
15537
15849
</UL>
15538
<H3><A name="Warnings_nn12"></A>14.8.3 C/C++ Parser (300-399)</H3>
15850
<H3><A name="Warnings_nn12"></A>14.9.3 C/C++ Parser (300-399)</H3>
15539
15851
<UL>
15540
15852
<LI>301. <TT>class</TT> keyword used, but not in C++ mode.</LI>
15541
15853
<LI>302. Identifier '<EM>name</EM>' redefined (ignored).</LI>
15611
15923
<LI>394. operator new[] ignored.</LI>
15612
15924
<LI>395. operator delete[] ignored.</LI>
15613
15925
</UL>
15614
<H3><A name="Warnings_nn13"></A>14.8.4 Types and typemaps (400-499)</H3>
15926
<H3><A name="Warnings_nn13"></A>14.9.4 Types and typemaps (400-499)</H3>
15615
15927
<UL>
15616
15928
<LI>401. Nothing known about class 'name'. Ignored.</LI>
15617
15929
<LI>402. Base class 'name' is incomplete.</LI>
15636
15948
instead.</LI>
15637
15949
<LI>471. Unable to use return type<EM> type</EM> in director method</LI>
15638
15950
</UL>
15639
<H3><A name="Warnings_nn14"></A>14.8.5 Code generation (500-599)</H3>
15951
<H3><A name="Warnings_nn14"></A>14.9.5 Code generation (500-599)</H3>
15640
15952
<UL>
15641
15953
<LI>501. Overloaded declaration ignored.<EM> decl</EM></LI>
15642
15954
<LI>502. Overloaded constructor ignored.<EM> decl</EM></LI>
15663
15975
<LI>518. Portability warning: File<EM> file1</EM> will be overwritten by<EM>
15664
15976
file2</EM> on case insensitive filesystems such as Windows' FAT32 and
15665
15977
NTFS unless the class/module name is renamed.</LI>
15978
<LI>519. %template() contains no name. Template method ignored:<EM>
15979
declaration</EM></LI>
15666
15980
</UL>
15667
<H3><A name="Warnings_nn15"></A>14.8.6 Language module specific
15981
<H3><A name="Warnings_nn15"></A>14.9.6 Language module specific
15668
15982
(800-899)</H3>
15669
15983
<UL>
15670
15984
<LI>801. Wrong name (corrected to '<EM>name</EM>'). (Ruby).</LI>
15717
16031
ignored. Multiple inheritance is not supported in Php4. (Php).</LI>
15718
16032
<LI>871. Unrecognized pragma<EM> pragma</EM>. (Php).</LI>
15719
16033
</UL>
15720
<H3><A name="Warnings_nn16"></A>14.8.7 User defined (900-999)</H3>
16034
<H3><A name="Warnings_nn16"></A>14.9.7 User defined (900-999)</H3>
15721
16035
<P> These numbers can be used by your own application.</P>
15722
<H2><A name="Warnings_nn17"></A>14.9 History</H2>
16036
<H2><A name="Warnings_nn17"></A>14.10 History</H2>
15723
16037
<P> The ability to control warning messages was first added to
15724
16038
SWIG-1.3.12.</P>
15725
16039
<HR NOSHADE>
15728
16042
<!-- INDEX -->
15729
16043
<DIV class="sectiontoc">
15730
16044
<UL>
16045
<LI><A href="#Modules_nn1">Basics</A></LI>
15731
16046
<LI><A href="#Modules_nn2">The SWIG runtime code</A></LI>
15732
16047
<LI><A href="#external_run_time">External access to the runtime</A></LI>
15733
16048
<LI><A href="#Modules_nn4">A word of caution about static libraries</A></LI>
15745
16060
target language interface when it is broken up into smaller pieces.</P>
15746
16061
<P> This chapter describes the problem of using SWIG in programs where
15747
16062
you want to create a collection of modules.</P>
15748
<H2><A name="Modules_nn2"></A>15.1 The SWIG runtime code</H2>
16063
<H2><A name="Modules_nn1"></A>15.1 Basics</H2>
16064
<P> The basic usage case with multiple modules is when modules do not
16065
have cross-references (ie. when wrapping multiple independent C APIs).
16066
In that case, swig input files should just work out of the box - you
16067
simply create multiple wrapper .cxx files, link them into your
16068
application, and insert/load each in the scripting language runtime as
16069
you would do for the single module case.</P>
16070
<P> A bit more complex is the case in which modules need to share
16071
information. For example, when one module extends the class of the
16072
another by deriving from it:</P>
16073
<DIV class="code">
16074
<PRE>
16075
%module base
16076
16077
%inline %{
16078
class base {
16079
public:
16080
int foo(void);
16081
};
16082
%}
16083
</PRE>
16084
</DIV> <DIV class="code">
16085
<PRE>
16086
%module derived
16087
16088
%import "base.i"
16089
16090
%inline %{
16091
class derived : public base {
16092
public:
16093
int bar(void);
16094
};
16095
%}
16096
</PRE>
16097
</DIV>
16098
<P>To create the wrapper properly, module <TT>derived</TT> needs to know
16099
the <TT>base</TT> class and that it's interface is covered in another
16100
module. The line <TT>%import "base.i"</TT> lets SWIG know exactly that.
16101
The common mistake here is to <TT>%import</TT> the <TT>.h</TT> file
16102
instead of the <TT>.i</TT>, which sadly won't do the trick. Another
16103
issue to take care of is that multiple dependent wrappers should not be
16104
linked/loaded in parallel from multiple threads as SWIG provides no
16105
locking - for more on that issue, read on.</P>
16106
<H2><A name="Modules_nn2"></A>15.2 The SWIG runtime code</H2>
15749
16107
<P> Many of SWIG's target languages generate a set of functions commonly
15750
16108
known as the "SWIG runtime." These functions are primarily related to
15751
16109
the runtime type system which checks pointer types and performs other
15767
16125
target language namespace. During module initialization, type
15768
16126
information is loaded into the global data structure of type
15769
16127
information from all modules.</P>
15770
<P> This can present a problem with threads. If two modules try and load
15771
at the same time, the type information can become corrupt. SWIG
15772
currently does not provide any locking, and if you use threads, you
15773
must make sure that modules are loaded serially. Be careful if you use
15774
threads and the automatic module loading that some scripting languages
15775
provide. One solution is to load all modules before spawning any
15776
threads.</P>
15777
<H2><A name="external_run_time"></A>15.2 External access to the runtime</H2>
16128
<P> There are a few trade offs with this approach. This type information
16129
is global across all SWIG modules loaded, and can cause type conflicts
16130
between modules that were not designed to work together. To solve this
16131
approach, the SWIG runtime code uses a define SWIG_TYPE_TABLE to
16132
provide a unique type table. This behavior can be enabled when
16133
compiling the generated _wrap.cxx or _wrap.c file by adding
16134
-DSWIG_TYPE_TABLE=myprojectname to the command line argument.</P>
16135
<P> Then, only modules compiled with SWIG_TYPE_TABLE set to
16136
myprojectname will share type information. So if your project has three
16137
modules, all three should be compiled with
16138
-DSWIG_TYPE_TABLE=myprojectname, and then these three modules will
16139
share type information. But any other project's types will not
16140
interfere or clash with the types in your module.</P>
16141
<P> Another issue relating to the global type table is thread safety. If
16142
two modules try and load at the same time, the type information can
16143
become corrupt. SWIG currently does not provide any locking, and if you
16144
use threads, you must make sure that modules are loaded serially. Be
16145
careful if you use threads and the automatic module loading that some
16146
scripting languages provide. One solution is to load all modules before
16147
spawning any threads, or use SWIG_TYPE_TABLE to separate type tables so
16148
they do not clash with each other.</P>
16149
<P> Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in
16150
Lib/swigrun.swg and near the top of every generated module. This number
16151
gets incremented when the data structures change, so that SWIG modules
16152
generated with different versions can peacefully coexist. So the type
16153
structures are separated by the (SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION)
16154
pair, where by default SWIG_TYPE_TABLE is empty. Only modules compiled
16155
with the same pair will share type information.</P>
16156
<H2><A name="external_run_time"></A>15.3 External access to the runtime</H2>
15778
16157
<P>As described in <A href="#runtime_type_checker">The run-time type
15779
16158
checker</A>, the functions <TT>SWIG_TypeQuery</TT>, <TT>
15780
16159
SWIG_NewPointerObj</TT>, and others sometimes need to be called. Calling
15782
16161
embedded into the <TT>_wrap.c</TT> file, which has those declarations
15783
16162
available. If you need to call the SWIG run-time functions from another
15784
16163
C file, there is one header you need to include. To generate the header
15785
that needs to be included, run the following command:<DIV class="code">
16164
that needs to be included, run the following command:<DIV class="shell">
15786
16165
<PRE>
15787
16166
$ swig -python -external-runtime <filename>
15788
16167
</PRE>
15806
16185
you can distribute a package that can be compiled without SWIG
15807
16186
installed (this works because the header file is self-contained, and
15808
16187
does not need to link with anything).</P>
15809
<H2><A name="Modules_nn4"></A>15.3 A word of caution about static
16188
<P> This header will also use the -DSWIG_TYPE_TABLE described above, so
16189
when compiling any code which includes the generated header file should
16190
define the SWIG_TYPE_TABLE to be the same as the module whose types you
16191
are trying to access.</P>
16192
<H2><A name="Modules_nn4"></A>15.4 A word of caution about static
15810
16193
libraries</H2>
15811
16194
<P> When working with multiple SWIG modules, you should take care not to
15812
16195
use static libraries. For example, if you have a static library <TT>
15816
16199
can lead to unexpected or bizarre program behavior. When working with
15817
16200
dynamically loadable modules, you should try to work exclusively with
15818
16201
shared libraries.</P>
15819
<H2><A name="Modules_nn5"></A>15.4 References</H2>
16202
<H2><A name="Modules_nn5"></A>15.5 References</H2>
15820
16203
<P> Due to the complexity of working with shared libraries and multiple
15821
16204
modules, it might be a good idea to consult an outside reference. John
15822
16205
Levine's "Linkers and Loaders" is highly recommended.</P>
15823
<H2><A name="Modules_nn6"></A>15.5 Reducing the wrapper file size</H2>
16206
<H2><A name="Modules_nn6"></A>15.6 Reducing the wrapper file size</H2>
15824
16207
<P> Using multiple modules with the <TT>%import</TT> directive is the
15825
16208
most common approach to modularising large projects. In this way a
15826
16209
number of different wrapper files can be generated, thereby avoiding
17075
17458
%rename(__logand_assign__) *::operator&=;
17076
17459
%rename(__logior_assign__) *::operator|=;
17077
17460
17078
%rename(__lshift__) *::operator<
17079
<!--;
17461
%rename(__lshift__) *::operator<<;
17080
17462
%rename(__lshift_assign__) *::operator<<=;
17081
%rename(__rshift__) *::operator-->
17082
>;
17463
%rename(__rshift__) *::operator>>;
17083
17464
%rename(__rshift_assign__) *::operator>>=;
17084
17465
17085
17466
%rename(__eq__) *::operator==;
17086
17467
%rename(__ne__) *::operator!=;
17087
%rename(__lt__) *::operator
17088
<!--;
17089
%rename(__gt__) *::operator-->
17090
;
17468
%rename(__lt__) *::operator<;
17469
%rename(__gt__) *::operator>;
17091
17470
%rename(__lte__) *::operator<=;
17092
17471
%rename(__gte__) *::operator>=;
17093
17472
17575
17954
management when returning references to member variables</A></LI>
17576
17955
<LI><A href="#csharp_memory_management_objects">Memory management for
17577
17956
objects passed to the C++ layer</A></LI>
17957
<LI><A href="#csharp_date_marshalling">Date marshalling using the csin
17958
typemap and associated attributes</A></LI>
17959
<LI><A href="#csharp_date_properties">A date example demonstrating
17960
marshalling of C# properties</A></LI>
17961
<LI><A href="#csharp_partial_classes">Turning wrapped classes into
17962
partial classes</A></LI>
17963
<LI><A href="#csharp_extending_proxy_class">Extending proxy classes with
17964
additional C# code</A></LI>
17578
17965
</UL>
17579
17966
</LI>
17580
17967
</UL>
17708
18095
<DIV class="code">
17709
18096
<PRE>
17710
18097
$javaclassname -> $csclassname
18098
$&javaclassname -> $&csclassname
18099
$*javaclassname -> $*csclassname
17711
18100
$javainput -> $csinput
17712
18101
$jnicall -> $imcall
17713
18102
</PRE>
17714
18103
</DIV></LI>
17715
18104
<LI>
17716
<P> The intermediary classname has <TT>PINVOKE</TT> appended after the
17717
module name instead of <TT>JNI</TT>, for example <TT>modulenamePINVOKE</TT>
17718
.</P>
18105
<P> Unlike the "javain" typemap, the "csin" typemap does not support the
18106
'pgcpp' attribute as the C# module does not have a premature garbage
18107
collection prevention parameter. The "csin" typemap supports an
18108
additional optional attribute called 'cshin'. It should contain the
18109
parameter type and name whenever a <A href="#java_constructor_helper_function">
18110
constructor helper function</A> is generated due to the 'pre' or 'post'
18111
attributes. Note that 'pre', 'post' and 'cshin' attributes are not used
18112
for marshalling the property set. Please see the <A href="#csharp_date_marshalling">
18113
Date marshalling example</A> and <A href="#CSharp.html#csharp_date_properties">
18114
Date marshalling of properties example</A> for further understanding.</P>
17719
18115
</LI>
17720
18116
<LI>
17721
18117
<P> Support for asymmetric type marshalling. The 'ctype', 'imtype' and
17820
18216
</DIV>
17821
18217
<P> If C# attributes need adding to the <TT>set</TT> or <TT>get</TT>
17822
18218
part of C# properties, when wrapping C/C++ variables, they can be added
17823
using the 'csvarin' and 'csvarout' typemaps respectively.</P>
18219
using the 'csvarin' and 'csvarout' typemaps respectively. Note that the
18220
type used for the property is specified in the 'cstype' typemap. If the
18221
'out' attribute exists in this typemap, then the type used is from the
18222
'out' attribute.</P>
18223
</LI>
18224
<LI>
18225
<P> The intermediary classname has <TT>PINVOKE</TT> appended after the
18226
module name instead of <TT>JNI</TT>, for example <TT>modulenamePINVOKE</TT>
18227
.</P>
17824
18228
</LI>
17825
18229
<LI>
17826
18230
<P> The <TT>%csmethodmodifiers</TT> feature can also be applied to
17939
18343
SWIG_CSharpArithmeticException,
17940
18344
SWIG_CSharpDivideByZeroException,
17941
18345
SWIG_CSharpIndexOutOfRangeException,
18346
SWIG_CSharpInvalidCastException,
17942
18347
SWIG_CSharpInvalidOperationException,
17943
18348
SWIG_CSharpIOException,
17944
18349
SWIG_CSharpNullReferenceException,
18636
19041
</PRE>
18637
19042
</DIV>
18638
19043
<H3><A name="csharp_director_caveats"></A>17.4.3 Director caveats</H3>
18639
<P> There are a few gotchas with directors. The first is that the base
18640
class virtual method should not be called directly otherwise a stack
18641
overflow will occur due to recursive calls. This might be fixed in a
18642
future version of SWIG, but is likely to slow down virtual methods
18643
calls. For example, given <TT>Base</TT> as a director enabled class:</P>
18644
<DIV class="code">
18645
<PRE>
18646
class Base {
18647
public:
18648
virtual ~Base();
18649
virtual unsigned int UIntMethod(unsigned int x);
18650
};
18651
</PRE>
18652
</DIV>
18653
<P> Do not directly call the base method from a C# derived class:</P>
18654
<DIV class="code">
18655
<PRE>
18656
public class CSharpDerived : Base
18657
{
18658
public override uint UIntMethod(uint x)
18659
{
18660
return base.UIntMethod(x);
18661
}
18662
}
18663
</PRE>
18664
</DIV>
18665
<P> Secondly, if default parameters are used, it is recommended to
18666
follow a pattern of always calling a single method in any C# derived
18667
class. An example will clarify this and the reasoning behind the
18668
recommendation. Consider the following C++ class wrapped as a director
18669
class:</P>
19044
<P> There is a subtle gotcha with directors. If default parameters are
19045
used, it is recommended to follow a pattern of always calling a single
19046
method in any C# derived class. An example will clarify this and the
19047
reasoning behind the recommendation. Consider the following C++ class
19048
wrapped as a director class:</P>
18670
19049
<DIV class="code">
18671
19050
<PRE>
18672
19051
class Defaults {
18910
19289
}
18911
19290
%}
18912
19291
</PRE>
19292
</DIV>
19293
<H3><A name="csharp_date_marshalling"></A>17.5.3 Date marshalling using
19294
the csin typemap and associated attributes</H3>
19295
<P> The <A href="#nan_exception_typemap">NaN Exception example</A> is a
19296
simple example of the "javain" typemap and its 'pre' attribute. This
19297
example demonstrates how a C++ date class, say <TT>CDate</TT>, can be
19298
mapped onto the standard .NET date class, <TT>System.DateTime</TT> by
19299
using the 'pre', 'post' and 'pgcppname' attributes of the "csin"
19300
typemap (the C# equivalent to the "javain" typemap). The example is an
19301
equivalent to the <A href="#java_date_marshalling">Java Date
19302
marshalling example</A>. The idea is that the <TT>System.DateTime</TT>
19303
is used wherever the C++ API uses a <TT>CDate</TT>. Let's assume the
19304
code being wrapped is as follows:</P>
19305
<DIV class="code">
19306
<PRE>
19307
class CDate {
19308
public:
19309
CDate(int year, int month, int day);
19310
int getYear();
19311
int getMonth();
19312
int getDay();
19313
...
19314
};
19315
struct Action {
19316
static int doSomething(const CDate &dateIn, CDate &dateOut);
19317
Action(const CDate &date, CDate &dateOut);
19318
};
19319
</PRE>
19320
</DIV>
19321
<P> Note that <TT>dateIn</TT> is const and therefore read only and <TT>
19322
dateOut</TT> is a non-const output type.</P>
19323
<P> First let's look at the code that is generated by default, where the
19324
C# proxy class <TT>CDate</TT> is used in the proxy interface:</P>
19325
<DIV class="code">
19326
<PRE>
19327
public class Action : IDisposable {
19328
...
19329
public Action(CDate dateIn, CDate dateOut)
19330
: this(examplePINVOKE.new_Action(CDate.getCPtr(dateIn), CDate.getCPtr(dateOut)), true) {
19331
if (examplePINVOKE.SWIGPendingException.Pending)
19332
throw examplePINVOKE.SWIGPendingException.Retrieve();
19333
}
19334
19335
public int doSomething(CDate dateIn, CDate dateOut) {
19336
int ret = examplePINVOKE.Action_doSomething(swigCPtr,
19337
CDate.getCPtr(dateIn),
19338
CDate.getCPtr(dateOut));
19339
if (examplePINVOKE.SWIGPendingException.Pending)
19340
throw examplePINVOKE.SWIGPendingException.Retrieve();
19341
return ret;
19342
}
19343
}
19344
</PRE>
19345
</DIV>
19346
<P> The <TT>CDate &</TT> and <TT>const CDate &</TT> C# code is generated
19347
from the following two default typemaps:</P>
19348
<DIV class="code">
19349
<PRE>
19350
%typemap(cstype) SWIGTYPE & "$csclassname"
19351
%typemap(csin) SWIGTYPE & "$csclassname.getCPtr($csinput)"
19352
</PRE>
19353
</DIV>
19354
<P> where '$csclassname' is translated into the proxy class name, <TT>
19355
CDate</TT> and '$csinput' is translated into the name of the parameter,
19356
eg <TT>dateIn</TT>. From C#, the intention is then to call into a
19357
modifed API with something like:</P>
19358
<DIV class="code">
19359
<PRE>
19360
System.DateTime dateIn = new System.DateTime(2011, 4, 13);
19361
System.DateTime dateOut = new System.DateTime();
19362
19363
// Note in calls below, dateIn remains unchanged and dateOut
19364
// is set to a new value by the C++ call
19365
Action action = new Action(dateIn, out dateOut);
19366
dateIn = new System.DateTime(2012, 7, 14);
19367
</PRE>
19368
</DIV>
19369
<P> To achieve this mapping, we need to alter the default code
19370
generation slightly so that at the C# layer, a <TT>System.DateTime</TT>
19371
is converted into a <TT>CDate</TT>. The intermediary layer will still
19372
take a pointer to the underlying <TT>CDate</TT> class. The typemaps to
19373
achieve this are shown below.</P>
19374
<DIV class="code">
19375
<PRE>
19376
%typemap(cstype) const CDate& "System.DateTime"
19377
%typemap(csin,
19378
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);")
19379
const CDate &
19380
"$csclassname.getCPtr(temp$csinput)"
19381
19382
%typemap(cstype) CDate& "out System.DateTime"
19383
%typemap(csin,
19384
pre=" CDate temp$csinput = new CDate();",
19385
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
19386
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
19387
cshin="out $csinput") CDate &
19388
"$csclassname.getCPtr(temp$csinput)"
19389
19390
</PRE>
19391
</DIV>
19392
<P> The resulting generated proxy code in the <TT>Action</TT> class
19393
follows:</P>
19394
<DIV class="code">
19395
<PRE>
19396
public class Action : IDisposable {
19397
...
19398
public int doSomething(System.DateTime dateIn, out System.DateTime dateOut) {
19399
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
19400
CDate tempdateOut = new CDate();
19401
try {
19402
int ret = examplePINVOKE.Action_doSomething(swigCPtr,
19403
CDate.getCPtr(tempdateIn),
19404
CDate.getCPtr(tempdateOut));
19405
if (examplePINVOKE.SWIGPendingException.Pending)
19406
throw examplePINVOKE.SWIGPendingException.Retrieve();
19407
return ret;
19408
} finally {
19409
dateOut = new System.DateTime(tempdateOut.getYear(),
19410
tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
19411
}
19412
}
19413
19414
static private IntPtr SwigConstructAction(System.DateTime dateIn, out System.DateTime dateOut) {
19415
CDate tempdateIn = new CDate(dateIn.Year, dateIn.Month, dateIn.Day);
19416
CDate tempdateOut = new CDate();
19417
try {
19418
return examplePINVOKE.new_Action(CDate.getCPtr(tempdateIn), CDate.getCPtr(tempdateOut));
19419
} finally {
19420
dateOut = new System.DateTime(tempdateOut.getYear(),
19421
tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
19422
}
19423
}
19424
19425
public Action(System.DateTime dateIn, out System.DateTime dateOut)
19426
: this(Action.SwigConstructAction(dateIn, out dateOut), true) {
19427
if (examplePINVOKE.SWIGPendingException.Pending)
19428
throw examplePINVOKE.SWIGPendingException.Retrieve();
19429
}
19430
}
19431
</PRE>
19432
</DIV>
19433
<P> A few things to note:</P>
19434
<UL>
19435
<LI> The "cstype" typemap has changed the parameter type to <TT>
19436
System.DateTime</TT> instead of the default generated <TT>CDate</TT>
19437
proxy.</LI>
19438
<LI> The non-const <TT>CDate &</TT> type is marshalled as a reference
19439
parameter in C# as the date cannot be explicitly set once the object
19440
has been created, so a new object is created instead.</LI>
19441
<LI> The code in the 'pre' attribute appears before the intermediary
19442
call (<TT>examplePINVOKE.new_Action</TT> / <TT>
19443
examplePINVOKE.Action_doSomething</TT>).</LI>
19444
<LI> The code in the 'post' attribute appears after the intermediary
19445
call.</LI>
19446
<LI> A try .. finally block is generated with the intermediary call in
19447
the try block and 'post' code in the finally block. The alternative of
19448
just using a temporary variable for the return value from the
19449
intermediary call and the 'post' code being inserted before the return
19450
statement is not possible given that the intermediary call and method
19451
return comes from a single source (the "csout" typemap).</LI>
19452
<LI> The temporary variables in the "csin" typemaps are called <TT>
19453
temp$csin</TT>, where "$csin" is replaced with the parameter name.
19454
"$csin" is used to mangle the variable name so that more than one <TT>
19455
CDate &</TT> type can be used as a parameter in a method, otherwise two
19456
or more local variables with the same name would be generated.</LI>
19457
<LI> The use of the "csin" typemap causes a constructor helper function
19458
(<TT>SwigConstructAction</TT>) to be generated. This allows C# code to
19459
be called before the intermediary call made in the constructor
19460
initialization list.</LI>
19461
<LI> The 'cshin' attribute is required for the <TT>SwigConstructAction</TT>
19462
constructor helper function so that the 2nd parameter is declared as <TT>
19463
out dateOut</TT> instead of just <TT>dateOut</TT>.</LI>
19464
</UL>
19465
<P> So far we have considered the date as an input only and an output
19466
only type. Now let's consider <TT>CDate *</TT> used as an input/output
19467
type. Consider the following C++ function which modifies the date
19468
passed in:</P>
19469
<DIV class="code">
19470
<PRE>
19471
void addYears(CDate *pDate, int years) {
19472
*pDate = CDate(pDate->getYear() + years, pDate->getMonth(), pDate->getDay());
19473
}
19474
</PRE>
19475
</DIV>
19476
<P> If usage of <TT>CDate *</TT> commonly follows this input/output
19477
pattern, usage from C# like the following</P>
19478
<DIV class="code">
19479
<PRE>
19480
System.DateTime christmasEve = new System.DateTime(2000, 12, 24);
19481
example.addYears(ref christmasEve, 10); // christmasEve now contains 2010-12-24
19482
</PRE>
19483
</DIV>
19484
<P> will be possible with the following <TT>CDate *</TT> typemaps</P>
19485
<DIV class="code">
19486
<PRE>
19487
%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
19488
19489
%typemap(csin,
19490
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
19491
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
19492
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
19493
cshin="ref $csinput") CDate *
19494
"$csclassname.getCPtr(temp$csinput)"
19495
</PRE>
19496
</DIV>
19497
<P> Globals are wrapped by the module class and for a module called
19498
example, the typemaps result in the following code:</P>
19499
<DIV class="code">
19500
<PRE>
19501
public class example {
19502
public static void addYears(ref System.DateTime pDate, int years) {
19503
CDate temppDate = new CDate(pDate.Year, pDate.Month, pDate.Day);
19504
try {
19505
examplePINVOKE.addYears(CDate.getCPtr(temppDate), years);
19506
} finally {
19507
pDate = new System.DateTime(temppDate.getYear(), temppDate.getMonth(), temppDate.getDay(), 0, 0, 0);
19508
}
19509
}
19510
...
19511
}
19512
</PRE>
19513
</DIV>
19514
<H3><A name="csharp_date_properties"></A>17.5.4 A date example
19515
demonstrating marshalling of C# properties</H3>
19516
<P> The previous section looked at converting a C++ date class to <TT>
19517
System.DateTime</TT> for parameters. This section extends this idea so
19518
that the correct marshalling is obtained when wrapping C++ variables.
19519
Consider the same <TT>CDate</TT> class from the previous section and a
19520
global variable:</P>
19521
<DIV class="code">
19522
<PRE>
19523
CDate ImportantDate = CDate(1999, 12, 31);
19524
</PRE>
19525
</DIV>
19526
<P> The aim is to use <TT>System.DateTime</TT> from C# when accessing
19527
this date as shown in the following usage where the module name is
19528
'example':</P>
19529
<DIV class="code">
19530
<PRE>
19531
example.ImportantDate = new System.DateTime(2000, 11, 22);
19532
System.DateTime importantDate = example.ImportantDate;
19533
Console.WriteLine("Important date: " + importantDate);
19534
</PRE>
19535
</DIV>
19536
<P> When SWIG wraps a variable that is a class/struct/union, it is
19537
wrapped using a pointer to the type for the reasons given in <A href="#SWIG_structure_data_members">
19538
Stucture data members</A>. The typemap type required is thus <TT>CDate *</TT>
19539
. Given that the previous section already designed <TT>CDate *</TT>
19540
typemaps, we'll use those same typemaps plus the 'csvarin' and
19541
'csvarout' typemaps.<DIV class="code">
19542
<PRE>
19543
%typemap(cstype, out="System.DateTime") CDate * "ref System.DateTime"
19544
19545
%typemap(csin,
19546
pre=" CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);",
19547
post=" $csinput = new System.DateTime(temp$csinput.getYear(),"
19548
" temp$csinput.getMonth(), temp$csinput.getDay(), 0, 0, 0);",
19549
cshin="ref $csinput") CDate *
19550
"$csclassname.getCPtr(temp$csinput)"
19551
19552
%typemap(csvarin, excode=SWIGEXCODE2) CDate * %{
19553
/* csvarin typemap code */
19554
set {
19555
CDate temp$csinput = new CDate($csinput.Year, $csinput.Month, $csinput.Day);
19556
$imcall;$excode
19557
} %}
19558
19559
%typemap(csvarout, excode=SWIGEXCODE2) CDate * %{
19560
/* csvarout typemap code */
19561
get {
19562
IntPtr cPtr = $imcall;
19563
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, $owner);$excode
19564
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
19565
0, 0, 0);
19566
} %}
19567
</PRE>
19568
</DIV></P>
19569
<P> For a module called example, the typemaps result in the following
19570
code:</P>
19571
<DIV class="code">
19572
<PRE>
19573
public class example {
19574
public static System.DateTime ImportantDate {
19575
/* csvarin typemap code */
19576
set {
19577
CDate tempvalue = new CDate(value.Year, value.Month, value.Day);
19578
examplePINVOKE.ImportantDate_set(CDate.getCPtr(tempvalue));
19579
}
19580
/* csvarout typemap code */
19581
get {
19582
IntPtr cPtr = examplePINVOKE.ImportantDate_get();
19583
CDate tempDate = (cPtr == IntPtr.Zero) ? null : new CDate(cPtr, false);
19584
return new System.DateTime(tempDate.getYear(), tempDate.getMonth(), tempDate.getDay(),
19585
0, 0, 0);
19586
}
19587
}
19588
...
19589
}
19590
</PRE>
19591
</DIV>
19592
<P> Some points to note:</P>
19593
<UL>
19594
<LI>The property set comes from the 'csvarin' typemap and the property
19595
get comes from the 'csvarout' typemap.</LI>
19596
<LI>The type used for the property comes from the 'cstype' typemap. This
19597
particular example has the 'out' attribute set in the typemap and as it
19598
is specified, it is used in preference to the type in the typemap body.
19599
This is because the type in the 'out' attribute can never include
19600
modifiers such as 'ref', thereby avoiding code such as <TT>public
19601
static ref System.DateTime ImportantDate { ...</TT>, which would of
19602
course not compile.</LI>
19603
<LI>The <TT>$excode</TT> special variable expands to nothing as there
19604
are no exception handlers specified in any of the unmanaged code
19605
typemaps (in fact the marshalling was done using the default unmanaged
19606
code typemaps.)</LI>
19607
<LI>The <TT>$imcall</TT> typemap expands to the appropriate intermediary
19608
method call in the <TT>examplePINVOKE</TT> class.</LI>
19609
<LI>The <TT>$csinput</TT> special variable in the 'csin' typemap always
19610
expands to <TT>value</TT> for properties. In this case <TT>
19611
$csclassname.getCPtr(temp$csinput)</TT> expands to <TT>
19612
CDate.getCPtr(tempvalue)</TT>.</LI>
19613
<LI>The 'csin' typemap has 'pre', 'post' and 'cshin' attributes, and
19614
these are all ignored in the property set. The code in these attributes
19615
must instead be replicated within the 'csvarin' typemap. The line
19616
creating the <TT>temp$csinput</TT> variable is such an example; it is
19617
identical to what is in the 'pre' attribute.</LI>
19618
</UL>
19619
<H3><A name="csharp_partial_classes"></A>17.5.5 Turning wrapped classes
19620
into partial classes</H3>
19621
<P> C# supports the notion of partial classes whereby a class definition
19622
can be split into more than one file. It is possible to turn the
19623
wrapped C++ class into a partial C# class using the <TT>
19624
csclassmodifiers</TT> typemap. Consider a C++ class called <TT>ExtendMe</TT>
19625
:</P>
19626
<DIV class="code">
19627
<PRE>
19628
class ExtendMe {
19629
public:
19630
int Part1() { return 1; }
19631
};
19632
</PRE>
19633
</DIV>
19634
<P> The default C# proxy class generated is:</P>
19635
<DIV class="code">
19636
<PRE>
19637
public class ExtendMe : IDisposable {
19638
...
19639
public int Part1() {
19640
...
19641
}
19642
}
19643
</PRE>
19644
</DIV>
19645
<P> The default csclassmodifiers typemap shipped with SWIG is</P>
19646
<DIV class="code">
19647
<PRE>
19648
%typemap(csclassmodifiers) SWIGTYPE "public class"
19649
</PRE>
19650
</DIV>
19651
<P> Note that the type used is the special catch all type <TT>SWIGTYPE</TT>
19652
. If instead we use the following typemap to override this for just the <TT>
19653
ExtendMe</TT> class:</P>
19654
<DIV class="code">
19655
<PRE>
19656
%typemap(csclassmodifiers) ExtendMe "public partial class"
19657
</PRE>
19658
</DIV>
19659
<P> The C# proxy class becomes a partial class:</P>
19660
<DIV class="code">
19661
<PRE>
19662
public partial class ExtendMe : IDisposable {
19663
...
19664
public int Part1() {
19665
...
19666
}
19667
}
19668
</PRE>
19669
</DIV>
19670
<P> You can then of course declare another part of the partial class
19671
elsewhere, for example:</P>
19672
<DIV class="code">
19673
<PRE>
19674
public partial class ExtendMe : IDisposable {
19675
public int Part2() {
19676
return 2;
19677
}
19678
}
19679
</PRE>
19680
</DIV>
19681
<P> and compile the following code:</P>
19682
<DIV class="code">
19683
<PRE>
19684
ExtendMe em = new ExtendMe();
19685
Console.WriteLine("part1: {0}", em.Part1());
19686
Console.WriteLine("part2: {0}", em.Part2());
19687
</PRE>
19688
</DIV>
19689
<P> demonstrating that the class contains methods calling both unmanaged
19690
code - <TT>Part1()</TT> and managed code - <TT>Part2()</TT>. The
19691
following example is an alternative approach to adding managed code to
19692
the generated proxy class.</P>
19693
<H3><A name="csharp_extending_proxy_class"></A>17.5.6 Extending proxy
19694
classes with additional C# code</H3>
19695
<P> The previous example showed how to use partial classes to add
19696
functionality to a generated C# proxy class. It is also possible to
19697
extend a wrapped struct/class with C/C++ code by using the <A href="#SWIGPlus_class_extension">
19698
%extend directive</A>. A third approach is to add some C# methods into
19699
the generated proxy class with the <TT>cscode</TT> typemap. If we
19700
declare the following typemap before SWIG parses the <TT>ExtendMe</TT>
19701
class used in the previous example</P>
19702
<DIV class="code">
19703
<PRE>
19704
%typemap(cscode) ExtendMe %{
19705
public int Part3() {
19706
return 3;
19707
}
19708
%}
19709
19710
</PRE>
19711
</DIV>
19712
<P> The generated C# proxy class will instead be:</P>
19713
<DIV class="code">
19714
<PRE>
19715
public class ExtendMe : IDisposable {
19716
...
19717
public int Part3() {
19718
return 3;
19719
}
19720
public int Part1() {
19721
...
19722
}
19723
}
19724
</PRE>
18913
19725
</DIV><HR NOSHADE>
18914
19726
18915
19727
<!-- Hand-written HTML -->
20202
21014
<LI><A href="#proxy_classes_gc">Proxy classes and garbage collection</A></LI>
20203
21015
<LI><A href="#java_pgcpp">The premature garbage collection prevention
20204
21016
parameter for proxy class marshalling</A></LI>
21017
<LI><A href="#java_multithread_libraries">Single threaded applications
21018
and thread safety</A></LI>
20205
21019
</UL>
20206
21020
</LI>
20207
21021
<LI><A href="#type_wrapper_classes">Type wrapper classes</A></LI>
20239
21053
<LI><A href="#simple_pointers">Simple pointers</A></LI>
20240
21054
<LI><A href="#c_arrays">Wrapping C arrays with Java arrays</A></LI>
20241
21055
<LI><A href="#unbounded_c_arrays">Unbounded C Arrays</A></LI>
21056
<LI><A href="#java_heap_allocations">Overriding new and delete to
21057
allocate from Java heap</A></LI>
20242
21058
</UL>
20243
21059
</LI>
20244
21060
<LI><A href="#java_typemaps">Java typemaps</A>
20284
21100
when returning references to member variables</A></LI>
20285
21101
<LI><A href="#java_memory_management_objects">Memory management for
20286
21102
objects passed to the C++ layer</A></LI>
21103
<LI><A href="#java_date_marshalling">Date marshalling using the javain
21104
typemap and associated attributes</A></LI>
20287
21105
</UL>
20288
21106
</LI>
20289
21107
<LI><A href="#java_directors_faq">Living with Java Directors</A></LI>
20615
21433
<H4><A name="visual_studio"></A>20.2.8.1 Running SWIG from Visual Studio</H4>
20616
21434
<P> If you are developing your application within Microsoft Visual
20617
21435
studio, SWIG can be invoked as a custom build option. The Examples\java
20618
directory has a few <A href="#examples">Windows Examples</A> containing
20619
Visual Studio project (.dsp) files. The process to re-create the
20620
project files for a C project are roughly:</P>
21436
directory has a few <A href="Windows.html#examples">Windows Examples</A>
21437
containing Visual Studio project (.dsp) files. The process to re-create
21438
the project files for a C project are roughly:</P>
20621
21439
<UL>
20622
21440
<LI>Open up a new workspace and use the AppWizard to select a DLL
20623
21441
project.</LI>
20840
21658
</DIV>
20841
21659
<P> The <TT>%immutable</TT> directive stays in effect until it is
20842
21660
explicitly disabled or cleared using <TT>%mutable</TT>. See the <A href="#SWIG_readonly_variables">
20843
Creatng read-only variables</A> section for further details.</P>
21661
Creating read-only variables</A> section for further details.</P>
20844
21662
<P> If you just want to make a specific variable immutable, supply a
20845
21663
declaration name. For example:</P>
20846
21664
<DIV class="code">
20957
21775
</DIV>
20958
21776
<P> Note: declarations declared as <TT>const</TT> are wrapped as
20959
21777
read-only variables and will be accessed using a getter as described in
20960
the previous section. They are not wrapped as constants.</P>
21778
the previous section. They are not wrapped as constants. The exception
21779
to this rule are static const integral values defined within a
21780
class/struct, where they are wrapped as constants, eg:.</P>
21781
<DIV class="code">
21782
<PRE>
21783
struct Maths {
21784
static const int FIVE = 5;
21785
};
21786
</PRE>
21787
</DIV>
20961
21788
<P><B> Compatibility Note:</B> In SWIG-1.3.19 and earlier releases, the
20962
21789
constants were generated into the module class and the constants
20963
21790
interface didn't exist. Backwards compatibility is maintained as the
21622
22449
Method spam(int) at example.i:11 used.
21623
22450
</PRE>
21624
22451
</DIV>
21625
<P> To fix this, you either need to ignore or rename one of the methods.
21626
For example:</P>
22452
<P> To fix this, you either need to either <A href="#SWIG_rename_ignore">
22453
rename or ignore</A> one of the methods. For example:</P>
21627
22454
<DIV class="code">
21628
22455
<PRE>
21629
%rename(spam_short) spam(short);
22456
%rename(spam_ushort) spam(unsigned short);
21630
22457
...
21631
22458
void spam(int);
21632
void spam(short); // Accessed as spam_short
22459
void spam(unsigned short); // Now renamed to spam_ushort
21633
22460
</PRE>
21634
22461
</DIV>
21635
22462
<P> or</P>
21636
22463
<DIV class="code">
21637
22464
<PRE>
21638
%ignore spam(short);
22465
%ignore spam(unsigned short);
21639
22466
...
21640
22467
void spam(int);
21641
void spam(short); // Ignored
22468
void spam(unsigned short); // Ignored
21642
22469
</PRE>
21643
22470
</DIV>
21644
22471
<H3><A name="java_default_arguments"></A>20.3.12 C++ default arguments</H3>
21722
22549
<PRE>
21723
22550
%module example
21724
22551
%{
21725
#include "pair.h"
22552
#include <utility>
21726
22553
%}
21727
22554
21728
22555
template<class T1, class T2>
21908
22735
code. This approach has a downside though as the proxy class might get
21909
22736
collected before the native method has completed. You might notice
21910
22737
above that there is an additional parameters with a underscore postfix,
21911
eg <TT>jarg1_</TT>. These are added in order to prevent <A href="java_pgcpp">
22738
eg <TT>jarg1_</TT>. These are added in order to prevent <A href="#java_pgcpp">
21912
22739
premature garbage collection when marshalling proxy classes</A>.</P>
21913
22740
<P> The functions in the intermediary JNI class cannot be accessed
21914
22741
outside of its package. Access to them is gained through the module
22040
22867
section for further details on using pragmas.</P>
22041
22868
<H3><A name="java_proxy_classes"></A>20.4.3 Java proxy classes</H3>
22042
22869
<P> A Java proxy class is generated for each structure, union or C++
22043
class that is wrapped. The default proxy class for our previous example
22044
looks like this:</P>
22870
class that is wrapped. Proxy classes have also been called <A href="http://java.sun.com/developer/JDCTechTips/2001/tt0612.html#tip2">
22871
peer classes</A>. The default proxy class for our previous example looks
22872
like this:</P>
22045
22873
<DIV class="code">
22046
22874
<PRE>
22047
22875
public class Foo {
22537
23365
a slight performance overhead and the parameter generation can be
22538
23366
suppressed globally with the <TT>-nopgcpp</TT> commandline option. More
22539
23367
selective suppression is possible with the 'nopgcpp' attribute in the
22540
"jnitype" <A href="#java_typemaps">Java typemap</A>. The attribute is a
23368
"jtype" <A href="#java_typemaps">Java typemap</A>. The attribute is a
22541
23369
flag and so should be set to "1" to enable the suppression, or it can
22542
23370
be omitted or set to "0" to disable. For example:</P>
22543
23371
<DIV class="code">
22547
23375
</DIV>
22548
23376
<P><B> Compatibility note:</B> The generation of this additional
22549
23377
parameter did not occur in versions prior to SWIG-1.3.30.</P>
23378
<H4><A name="java_multithread_libraries"></A>20.4.3.5 Single threaded
23379
applications and thread safety</H4>
23380
<P> Single threaded Java applications using JNI need to consider thread
23381
safety. The same applies for the C# module where the .NET wrappers use
23382
PInvoke. Consider the C++ class:</P>
23383
<DIV class="code">
23384
<PRE>
23385
class Test {
23386
string str;
23387
public:
23388
Test() : str("initial") {}
23389
};
23390
</PRE>
23391
</DIV>
23392
<P> and the Java proxy class generated by SWIG:</P>
23393
<DIV class="code">
23394
<PRE>
23395
public class Test {
23396
private long swigCPtr;
23397
protected boolean swigCMemOwn;
23398
23399
protected Test(long cPtr, boolean cMemoryOwn) {
23400
swigCMemOwn = cMemoryOwn;
23401
swigCPtr = cPtr;
23402
}
23403
23404
protected static long getCPtr(Test obj) {
23405
return (obj == null) ? 0 : obj.swigCPtr;
23406
}
23407
23408
protected void finalize() {
23409
delete();
23410
}
23411
23412
// Call C++ destructor
23413
public synchronized void delete() {
23414
if(swigCPtr != 0 && swigCMemOwn) {
23415
swigCMemOwn = false;
23416
exampleJNI.delete_Test(swigCPtr);
23417
}
23418
swigCPtr = 0;
23419
}
23420
23421
// Call C++ constructor
23422
public Test() {
23423
this(exampleJNI.new_Test(), true);
23424
}
23425
23426
}
23427
</PRE>
23428
</DIV>
23429
<P> It has two methods that call JNI methods, namely, <TT>
23430
exampleJNI.new_Test()</TT> for the C++ constructor and <TT>
23431
exampleJNI.delete_Test()</TT> for the C++ destructor. If the garbage
23432
collector collects an instance of this class, ie <TT>delete()</TT> is
23433
not explicitly called, then the C++ destructor will be run in a
23434
different thread to the main thread. This is because when an object is
23435
marked for garbage collection, any objects with finalizers are added to
23436
a finalization queue and the objects in the finalization queue have
23437
their <TT>finalize()</TT> methods run in a separate finalization
23438
thread. Therefore, if the C memory allocator is not thread safe, then
23439
the heap will get corrupted sooner or later, when a concurrent C++
23440
delete and new are executed. It is thus essential, even in single
23441
threaded usage, to link to the C multi-thread runtime libraries, for
23442
example, use the /MD option for Visual C++ on Windows. Alternatively,
23443
lock all access to C++ functions that have heap
23444
allocation/deallocation.</P>
23445
<P> Note that some of the STL in Visual C++ 6 is not thread safe, so
23446
although code might be linked to the multithread runtime libraries,
23447
undefined behaviour might still occur in a single threaded Java
23448
program. Similarly some older versions of Sun Studio have bugs in the
23449
multi-threaded implementation of the std::string class and so will lead
23450
to undefined behaviour in these supposedly single threaded Java
23451
applications.</P>
23452
<P> The following innocuous Java usage of Test is an example that will
23453
crash very quickly on a multiprocessor machine if the JNI compiled code
23454
is linked against the single thread C runtime libraries.</P>
23455
<DIV class="code">
23456
<PRE>
23457
for (int i=0; i<100000; i++) {
23458
System.out.println("Iteration " + i);
23459
for (int k=0; k<10; k++) {
23460
Test test = new Test();
23461
}
23462
System.gc();
23463
}
23464
</PRE>
23465
</DIV>
22550
23466
<H3><A name="type_wrapper_classes"></A>20.4.4 Type wrapper classes</H3>
22551
23467
<P> The generated type wrapper class, for say an <TT>int *</TT>, looks
22552
23468
like this:</P>
23128
24044
void *malloc(size_t nbytes);
23129
24045
</PRE>
23130
24046
</DIV>
23131
<P> No declaration name is given to <TT>%exception</TT>, it is applied
23132
to all wrapper functions. The <TT>$action</TT> is a SWIG special
23133
variable and is replaced by the C/C++ function call being wrapped. The <TT>
23134
return $null;</TT> handles all native method return types, namely those
23135
that have a void return and those that do not. This is useful for
23136
typemaps that will be used in native method returning all return types.
23137
See the section on <A href="#special_variables">Java special variables</A>
23138
for further explanation.</P>
24047
<P> If no declaration name is given to <TT>%exception</TT>, it is
24048
applied to all wrapper functions. The <TT>$action</TT> is a SWIG
24049
special variable and is replaced by the C/C++ function call being
24050
wrapped. The <TT>return $null;</TT> handles all native method return
24051
types, namely those that have a void return and those that do not. This
24052
is useful for typemaps that will be used in native method returning all
24053
return types. See the section on <A href="#special_variables">Java
24054
special variables</A> for further explanation.</P>
23139
24055
<P> C++ exceptions are also easy to handle. We can catch the C++
23140
24056
exception and rethrow it as a Java exception like this:</P>
23141
24057
<DIV class="code">
23197
24113
</DIV>
23198
24114
<P> The examples above first use the C JNI calling syntax then the C++
23199
24115
JNI calling syntax. The C++ calling syntax will not compile as C and
23200
also visa versa. It is however possible to write JNI calls which will
24116
also vice versa. It is however possible to write JNI calls which will
23201
24117
compile under both C and C++ and is covered in the <A href="#typemaps_for_c_and_c++">
23202
24118
Typemaps for both C and C++ compilation</A> section.</P>
23203
24119
<P> The language-independent <TT>exception.i</TT> library file can also
23411
24327
int array[4];
23412
24328
void populate(int x[]) {
23413
24329
int i;
23414
for (i=0; i
23415
<!--4; i++)
24330
for (i=0; i<4; i++)
23416
24331
x[i] = 100 + i;
23417
24332
}
23418
</pre-->
23419
23420
24333
</PRE>
23421
24334
</DIV>
23422
24335
<P> These one dimensional arrays can then be used as if they were Java
23531
24444
<DIV class="code">
23532
24445
<PRE>
23533
24446
SWIGTYPE_p_int array = example.new_intArray(10000000); // Array of 10-million integers
23534
for (int i=0; i
23535
<!--10000; i++) { // Set some values
24447
for (int i=0; i<10000; i++) { // Set some values
23536
24448
example.intArray_setitem(array,i,i);
23537
24449
}
23538
24450
int sum = example.sumitems(array,10000);
23539
24451
System.out.println("Sum = " + sum);
23540
</pre-->
23541
23542
24452
</PRE>
23543
24453
</DIV>
23544
24454
<P> If you replace <TT>%array_functions(int,intp)</TT> by <TT>
23558
24468
<DIV class="code">
23559
24469
<PRE>
23560
24470
intArray array = new intArray(10000000); // Array of 10-million integers
23561
for (int i=0; i
23562
<!--10000; i++) { // Set some values
24471
for (int i=0; i<10000; i++) { // Set some values
23563
24472
array.setitem(i,i);
23564
24473
}
23565
24474
int sum = example.sumitems(array.cast(),10000);
23566
24475
System.out.println("Sum = " + sum);
23567
</pre-->
23568
23569
24476
</PRE>
23570
24477
</DIV>
23571
24478
<P> The array "object" created by <TT>%array_class()</TT> does not
23579
24486
other hand, this low-level approach is extremely efficient and well
23580
24487
suited for applications in which you need to create buffers, package
23581
24488
binary data, etc.</P>
24489
<H3><A name="java_heap_allocations"></A>20.7.5 Overriding new and delete
24490
to allocate from Java heap</H3>
24491
<P> Unlike some languages supported by SWIG, Java has a true garbage
24492
collection subsystem. Other languages will free SWIG wrapped objects
24493
when their reference count reaches zero. Java only schedules these
24494
objects for finalization, which may not occur for some time. Because
24495
SWIG objects are allocated on the C heap, Java users may find the JVM
24496
memory use quickly exceeds the assigned limits, as memory fills with
24497
unfinalized proxy objects. Forcing garbage collection is clearly an
24498
undesirable solution.</P>
24499
<P> An elegant fix for C++ users is to override new and delete using the
24500
following code (here shown included in a SWIG interface file)</P>
24501
<DIV class="code">
24502
<PRE>
24503
/* File: java_heap.i */
24504
%module test
24505
%{
24506
#include <stdexcept>
24507
#include "jni.h"
24508
24509
/**
24510
* A stash area embedded in each allocation to hold java handles
24511
*/
24512
struct Jalloc {
24513
jbyteArray jba;
24514
jobject ref;
24515
};
24516
24517
static JavaVM *cached_jvm = 0;
24518
24519
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *jvm, void *reserved) {
24520
cached_jvm = jvm;
24521
return JNI_VERSION_1_2;
24522
}
24523
24524
static JNIEnv * JNU_GetEnv() {
24525
JNIEnv *env;
24526
jint rc = cached_jvm->GetEnv((void **)&env, JNI_VERSION_1_2);
24527
if (rc == JNI_EDETACHED)
24528
throw std::runtime_error("current thread not attached");
24529
if (rc == JNI_EVERSION)
24530
throw std::runtime_error("jni version not supported");
24531
return env;
24532
}
24533
24534
void * operator new(size_t t) {
24535
if (cached_jvm != 0) {
24536
JNIEnv *env = JNU_GetEnv();
24537
jbyteArray jba = env->NewByteArray((int) t + sizeof(Jalloc));
24538
if (env->ExceptionOccurred())
24539
throw bad_alloc();
24540
void *jbuffer = static_cast<void *>(env->GetByteArrayElements(jba, 0));
24541
if (env->ExceptionOccurred())
24542
throw bad_alloc();
24543
Jalloc *pJalloc = static_cast<Jalloc *>(jbuffer);
24544
pJalloc->jba = jba;
24545
/* Assign a global reference so byte array will persist until delete'ed */
24546
pJalloc->ref = env->NewGlobalRef(jba);
24547
if (env->ExceptionOccurred())
24548
throw bad_alloc();
24549
return static_cast<void *>(static_cast<char *>(jbuffer) + sizeof(Jalloc));
24550
}
24551
else { /* JNI_OnLoad not called, use malloc and mark as special */
24552
Jalloc *pJalloc = static_cast<Jalloc *>(malloc((int) t + sizeof(Jalloc)));
24553
if (!pJalloc)
24554
throw bad_alloc();
24555
pJalloc->ref = 0;
24556
return static_cast<void *>(
24557
static_cast<char *>(static_cast<void *>(pJalloc)) + sizeof(Jalloc));
24558
}
24559
}
24560
24561
void operator delete(void *v) {
24562
if (v != 0) {
24563
void *buffer = static_cast<void *>( static_cast<char *>(v) - sizeof(Jalloc));
24564
Jalloc *pJalloc = static_cast<Jalloc *>(buffer);
24565
if (pJalloc->ref) {
24566
JNIEnv *env = JNU_GetEnv();
24567
env->DeleteGlobalRef(pJalloc->ref);
24568
env->ReleaseByteArrayElements(pJalloc->jba, static_cast<jbyte *>(buffer), 0);
24569
}
24570
else {
24571
free(buffer);
24572
}
24573
}
24574
}
24575
%}
24576
...
24577
</PRE>
24578
</DIV>
24579
<P> This code caches the Java environment during initialization, and
24580
when new is called, a Java ByteArray is allocated to provide the SWIG
24581
objects with space in the Java heap. This has the combined effect of
24582
re-asserting the Java virtual machine's limit on memory allocation, and
24583
puts additional pressure on the garbage collection system to run more
24584
frequently. This code is made slightly more complicated because
24585
allowances must be made if new is called before the JNI_OnLoad is
24586
executed. This can happen during static class initialization, for
24587
example.</P>
24588
<P> Unfortunately, because most Java implementations call malloc and
24589
free, this solution will not work for C wrapped structures. However,
24590
you are free to make functions that allocate and free memory from the
24591
Java heap using this model and use these functions in place of malloc
24592
and free in your own code.</P>
23582
24593
<H2><A name="java_typemaps"></A>20.8 Java typemaps</H2>
23583
24594
<P> This section describes how you can modify SWIG's default wrapping
23584
24595
behavior for various C/C++ datatypes using the <TT>%typemap</TT>
23980
24991
arrays of C strings to Java String arrays</TD></TR>
23981
24992
</TABLE>
23982
24993
<H3><A name="typemap_attributes"></A>20.8.6 Java typemap attributes</H3>
23983
<P> There is an additional typemap attribute that the Java module
23984
supports. This is the 'throws' attribute. The throws attribute is
23985
optional and specified after the typemap name and contains one or more
23986
comma separated classes for adding to the throws clause for any methods
23987
that use that typemap. It is analogous to the <A href="#exception_handling">
24994
<P> There are a few additional typemap attributes that the Java module
24995
supports.</P>
24996
<P> The first of these is the 'throws' attribute. The throws attribute
24997
is optional and specified after the typemap name and contains one or
24998
more comma separated classes for adding to the throws clause for any
24999
methods that use that typemap. It is analogous to the <A href="#exception_handling">
23988
25000
%javaexception</A> feature's throws attribute.</P>
23989
25001
<DIV class="code">
23990
25002
<PRE>
24003
25015
throws clause, the union of the exception classes is added to the
24004
25016
throws clause ensuring there are no duplicate classes. See the <A href="#nan_exception_typemap">
24005
25017
NaN exception example</A> for further usage.</P>
24006
<P> The "jnitype" typemap has the 'nopgcpp' attribute which can be used
24007
to suppress the generation of the <A href="java_pgcpp">premature
24008
garbage collection prevention parameter</A>.</P>
25018
<P> The "jtype" typemap has the optional 'nopgcpp' attribute which can
25019
be used to suppress the generation of the <A href="java_pgcpp">
25020
premature garbage collection prevention parameter</A>.</P>
25021
<P> The "javain" typemap has the optional 'pre', 'post' and 'pgcppname'
25022
attributes. These are used for generating code before and after the JNI
25023
call in the proxy class or module class. The 'pre' attribute contains
25024
code that is generated before the JNI call and the 'post' attribute
25025
contains code generated after the JNI call. The 'pgcppname' attribute
25026
is used to change the <A href="java_pgcpp">premature garbage collection
25027
prevention parameter</A> name passed to the JNI function. This is
25028
sometimes needed when the 'pre' typemap creates a temporary variable
25029
which is then passed to the JNI function.</P>
25030
<P> <A name="java_constructor_helper_function"></A> Note that when the
25031
'pre' or 'post' attributes are specified and the associated type is
25032
used in a constructor, a constructor helper function is generated. This
25033
is necessary as the Java proxy constructor wrapper makes a call to a
25034
support constructor using a<I> this</I> call. In Java the<I> this</I>
25035
call must be the first statement in the constructor body. The
25036
constructor body thus calls the helper function and the helper function
25037
instead makes the JNI call, ensuring the 'pre' code is called before
25038
the JNI call is made. There is a <A href="#java_date_marshalling">Date
25039
marshalling</A> example showing 'pre', 'post' and 'pgcppname'
25040
attributes in action.</P>
24009
25041
<H3><A name="special_variables"></A>20.8.7 Java special variables</H3>
24010
25042
<P> The standard SWIG special variables are available for use within
24011
25043
typemaps as described in the <A href="#Typemaps">Typemaps documentation</A>
24012
25044
, for example <TT>$1</TT>, <TT>$input</TT>,<TT>$result</TT> etc.</P>
24013
25045
<P> The Java module uses a few additional special variables:</P>
24014
25046
<P><B> <TT>$javaclassname</TT></B>
24015
<BR> <TT>$javaclassname</TT> is similar to <TT>$1_type</TT>. It expands
24016
to the class name for use in Java. When wrapping a union, struct or
24017
class, it expands to the Java proxy class name. Otherwise it expands to
24018
the type wrapper class name. For example, <TT>$javaclassname</TT> is
24019
replaced by <TT>Foo</TT> when the wrapping a <TT>struct Foo</TT> or <TT>
24020
struct Foo *</TT> and <TT>SWIGTYPE_p_unsigned_short</TT> is used for <TT>
24021
unsigned short *</TT>.</P>
25047
<BR> This special variable works like the other <A href="#Typemaps_special_variables">
25048
special variables</A> and <TT>$javaclassname</TT> is similar to <TT>
25049
$1_type</TT>. It expands to the class name for use in Java given a
25050
pointer. SWIG wraps unions, structs and classes using pointers and in
25051
this case it expands to the Java proxy class name. For example, <TT>
25052
$javaclassname</TT> is replaced by the proxy classname <TT>Foo</TT> when
25053
wrapping a <TT>Foo *</TT> and <TT>$&javaclassname</TT> expands to the
25054
proxy classname when wrapping the C/C++ type <TT>Foo</TT> and <TT>
25055
$*javaclassname</TT> expands to the proxy classname when wrapping <TT>
25056
Foo *&</TT>. If the type does not have an associated proxy class, it
25057
expands to the type wrapper class name, for example, <TT>
25058
SWIGTYPE_p_unsigned_short</TT> is generated when wrapping <TT>unsigned
25059
short *</TT>.</P>
24022
25060
<P><B> <TT>$null</TT></B>
24023
25061
<BR> Used in input typemaps to return early from JNI functions that have
24024
25062
either void or a non-void return type. Example:</P>
24734
25772
<P> Note that the "javain" typemap is used for every occurrence of a <TT>
24735
25773
float</TT> being used as an input. Of course, we could have targeted the
24736
25774
typemap at a particular parameter by using <TT>float first</TT>, say,
24737
instead of just <TT>float</TT>. If we decide that what we actually want
24738
is a checked exception instead of a runtime exception, we can change
24739
this easily enough. The proxy method that uses <TT>float</TT> as an
24740
input, must then add the exception class to the throws clause. SWIG can
24741
handle this as it supports the 'throws' <A href="#typemap_attributes">
24742
typemap attribute</A> for specifying classes for the throws clause. Thus
24743
we can modify the pragma and the typemap for the throws clause:</P>
25775
instead of just <TT>float</TT>.</P>
25776
<P> The exception checking could alternatively have been placed into the
25777
'pre' attribute that the "javain" typemap supports. The "javain"
25778
typemap above could be replaced with the following:</P>
25779
<DIV class="code">
25780
<PRE>
25781
%typemap(javain, pre=" $module.CheckForNaN($javainput);") float "$javainput"
25782
</PRE>
25783
</DIV>
25784
<P> which would modify the <TT>calculate</TT> function to instead be
25785
generated as:</P>
25786
<DIV class="code">
25787
<PRE>
25788
public class example {
25789
...
25790
public static boolean calculate(float first, float second) {
25791
example.CheckForNaN(first);
25792
example.CheckForNaN(second);
25793
{
25794
return exampleJNI.calculate(first, second);
25795
}
25796
}
25797
}
25798
</PRE>
25799
</DIV>
25800
<P> See the <A href="#java_date_marshalling">Date marshalling example</A>
25801
for an example using further "javain" typemap attributes.</P>
25802
<P> If we decide that what we actually want is a checked exception
25803
instead of a runtime exception, we can change this easily enough. The
25804
proxy method that uses <TT>float</TT> as an input, must then add the
25805
exception class to the throws clause. SWIG can handle this as it
25806
supports the 'throws' <A href="#typemap_attributes">typemap attribute</A>
25807
for specifying classes for the throws clause. Thus we can modify the
25808
pragma and the typemap for the throws clause:</P>
24744
25809
<DIV class="code">
24745
25810
<PRE>
24746
25811
%typemap(javain, throws="java.lang.Exception") float "$module.CheckForNaN($javainput)"
24802
25867
for (i = 0; i<size; i++) {
24803
25868
jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
24804
25869
const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
24805
$1[i] = malloc(strlen((c_string)+1)*sizeof(const char *));
25870
$1[i] = malloc((strlen(c_string)+1)*sizeof(char));
24806
25871
strcpy($1[i], c_string);
24807
25872
(*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
24808
25873
(*jenv)->DeleteLocalRef(jenv, j_string);
24842
25907
%typemap(jstype) char ** "String[]"
24843
25908
24844
25909
/* These 2 typemaps handle the conversion of the jtype to jstype typemap type
24845
and visa versa */
25910
and vice versa */
24846
25911
%typemap(javain) char ** "$javainput"
24847
25912
%typemap(javaout) char ** {
24848
25913
return $jnicall;
24950
26015
for (i = 0; i<$1; i++) {
24951
26016
jstring j_string = (jstring)(*jenv)->GetObjectArrayElement(jenv, $input, i);
24952
26017
const char * c_string = (*jenv)->GetStringUTFChars(jenv, j_string, 0);
24953
$2[i] = malloc(strlen((c_string)+1)*sizeof(const char *));
26018
$2[i] = malloc((strlen(c_string)+1)*sizeof(char));
24954
26019
strcpy($2[i], c_string);
24955
26020
(*jenv)->ReleaseStringUTFChars(jenv, j_string, c_string);
24956
26021
(*jenv)->DeleteLocalRef(jenv, j_string);
25739
26804
%}
25740
26805
</PRE>
25741
26806
</DIV>
26807
<H3><A name="java_date_marshalling"></A>20.9.13 Date marshalling using
26808
the javain typemap and associated attributes</H3>
26809
<P> The <A href="#nan_exception_typemap">NaN Exception example</A> is a
26810
simple example of the "javain" typemap and its 'pre' attribute. This
26811
example demonstrates how a C++ date class, say <TT>CDate</TT>, can be
26812
mapped onto the standard Java date class, <TT>
26813
java.util.GregorianCalendar</TT> by using the 'pre', 'post' and
26814
'pgcppname' attributes of the "javain" typemap. The idea is that the <TT>
26815
GregorianCalendar</TT> is used wherever the C++ API uses a <TT>CDate</TT>
26816
. Let's assume the code being wrapped is as follows:</P>
26817
<DIV class="code">
26818
<PRE>
26819
class CDate {
26820
public:
26821
CDate(int year, int month, int day);
26822
int getYear();
26823
int getMonth();
26824
int getDay();
26825
...
26826
};
26827
struct Action {
26828
static int doSomething(const CDate &dateIn, CDate &dateOut);
26829
Action(const CDate &date, CDate &dateOut);
26830
};
26831
</PRE>
26832
</DIV>
26833
<P> Note that <TT>dateIn</TT> is const and therefore read only and <TT>
26834
dateOut</TT> is a non-const output type.</P>
26835
<P> First let's look at the code that is generated by default, where the
26836
Java proxy class <TT>CDate</TT> is used in the proxy interface:</P>
26837
<DIV class="code">
26838
<PRE>
26839
public class Action {
26840
...
26841
public static int doSomething(CDate dateIn, CDate dateOut) {
26842
return exampleJNI.Action_doSomething(CDate.getCPtr(dateIn), dateIn,
26843
CDate.getCPtr(dateOut), dateOut);
26844
}
26845
26846
public Action(CDate date, CDate dateOut) {
26847
this(exampleJNI.new_Action(CDate.getCPtr(date), date,
26848
CDate.getCPtr(dateOut), dateOut), true);
26849
}
26850
}
26851
</PRE>
26852
</DIV>
26853
<P> The <TT>CDate &</TT> and <TT>const CDate &</TT> Java code is
26854
generated from the following two default typemaps:</P>
26855
<DIV class="code">
26856
<PRE>
26857
%typemap(jstype) SWIGTYPE & "$javaclassname"
26858
%typemap(javain) SWIGTYPE & "$javaclassname.getCPtr($javainput)"
26859
</PRE>
26860
</DIV>
26861
<P> where '$javaclassname' is translated into the proxy class name, <TT>
26862
CDate</TT> and '$javainput' is translated into the name of the
26863
parameter, eg <TT>dateIn</TT>. From Java, the intention is then to call
26864
into a modifed API with something like:</P>
26865
<DIV class="code">
26866
<PRE>
26867
java.util.GregorianCalendar calendarIn =
26868
new java.util.GregorianCalendar(2011, java.util.Calendar.APRIL, 13, 0, 0, 0);
26869
java.util.GregorianCalendar calendarOut = new java.util.GregorianCalendar();
26870
26871
// Note in calls below, calendarIn remains unchanged and calendarOut
26872
// is set to a new value by the C++ call
26873
Action.doSomething(calendarIn, calendarOut);
26874
Action action = new Action(calendarIn, calendarOut);
26875
</PRE>
26876
</DIV>
26877
<P> To achieve this mapping, we need to alter the default code
26878
generation slightly so that at the Java layer, a <TT>GregorianCalendar</TT>
26879
is converted into a <TT>CDate</TT>. The JNI intermediary layer will
26880
still take a pointer to the underlying <TT>CDate</TT> class. The
26881
typemaps to achieve this are shown below.</P>
26882
<DIV class="code">
26883
<PRE>
26884
%typemap(jstype) const CDate& "java.util.GregorianCalendar"
26885
%typemap(javain,
26886
pre=" CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
26887
"$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));",
26888
pgcppname="temp$javainput") const CDate &
26889
"$javaclassname.getCPtr(temp$javainput)"
26890
26891
%typemap(jstype) CDate& "java.util.Calendar"
26892
%typemap(javain,
26893
pre=" CDate temp$javainput = new CDate($javainput.get(java.util.Calendar.YEAR), "
26894
"$javainput.get(java.util.Calendar.MONTH), $javainput.get(java.util.Calendar.DATE));",
26895
post=" $javainput.set(temp$javainput.getYear(), temp$javainput.getMonth(), "
26896
"temp$javainput.getDay(), 0, 0, 0);",
26897
pgcppname="temp$javainput") CDate &
26898
"$javaclassname.getCPtr(temp$javainput)"
26899
</PRE>
26900
</DIV>
26901
<P> The resulting generated proxy code in the <TT>Action</TT> class
26902
follows:</P>
26903
<DIV class="code">
26904
<PRE>
26905
public class Action {
26906
...
26907
public static int doSomething(java.util.GregorianCalendar dateIn,
26908
java.util.Calendar dateOut) {
26909
CDate tempdateIn = new CDate(dateIn.get(java.util.Calendar.YEAR),
26910
dateIn.get(java.util.Calendar.MONTH),
26911
dateIn.get(java.util.Calendar.DATE));
26912
CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR),
26913
dateOut.get(java.util.Calendar.MONTH),
26914
dateOut.get(java.util.Calendar.DATE));
26915
try {
26916
return exampleJNI.Action_doSomething(CDate.getCPtr(tempdateIn), tempdateIn,
26917
CDate.getCPtr(tempdateOut), tempdateOut);
26918
} finally {
26919
dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
26920
}
26921
}
26922
26923
static private long SwigConstructAction(java.util.GregorianCalendar date,
26924
java.util.Calendar dateOut) {
26925
CDate tempdate = new CDate(date.get(java.util.Calendar.YEAR),
26926
date.get(java.util.Calendar.MONTH),
26927
date.get(java.util.Calendar.DATE));
26928
CDate tempdateOut = new CDate(dateOut.get(java.util.Calendar.YEAR),
26929
dateOut.get(java.util.Calendar.MONTH),
26930
dateOut.get(java.util.Calendar.DATE));
26931
try {
26932
return exampleJNI.new_Action(CDate.getCPtr(tempdate), tempdate,
26933
CDate.getCPtr(tempdateOut), tempdateOut);
26934
} finally {
26935
dateOut.set(tempdateOut.getYear(), tempdateOut.getMonth(), tempdateOut.getDay(), 0, 0, 0);
26936
}
26937
}
26938
26939
public Action(java.util.GregorianCalendar date, java.util.Calendar dateOut) {
26940
this(Action.SwigConstructAction(date, dateOut), true);
26941
}
26942
}
26943
</PRE>
26944
</DIV>
26945
<P> A few things to note:</P>
26946
<UL>
26947
<LI> The "javatype" typemap has changed the parameter type to <TT>
26948
java.util.GregorianCalendar</TT> or <TT>java.util.Calendar</TT> instead
26949
of the default generated <TT>CDate</TT> proxy.</LI>
26950
<LI> The code in the 'pre' attribute appears before the JNI call (<TT>
26951
exampleJNI.new_Action</TT> / <TT>exampleJNI.Action_doSomething</TT>).</LI>
26952
<LI> The code in the 'post' attribute appears after the JNI call.</LI>
26953
<LI> A try .. finally block is generated with the JNI call in the try
26954
block and 'post' code in the finally block. The alternative of just
26955
using a temporary variable for the return value from the JNI call and
26956
the 'post' code being generated before the return statement is not
26957
possible given that the JNI call is in one line and comes from the
26958
"javaout" typemap.</LI>
26959
<LI> The temporary variables in the "javain" typemaps are called <TT>
26960
temp$javain</TT>, where "$javain" is replaced with the parameter name.
26961
"$javain" is used to mangle the variable name so that more than one <TT>
26962
CDate &</TT> type can be used as a parameter in a method, otherwise two
26963
or more local variables with the same name would be generated.</LI>
26964
<LI> The use of the "javain" typemap causes a constructor helper
26965
function (<TT>SwigConstructAction</TT>) to be generated. This allows
26966
Java code to be called before the JNI call and is required as the Java
26967
compiler won't compile code inserted before the 'this' call.</LI>
26968
<LI> The 'pgcppname' attribute is used to modify the object being passed
26969
as the <A href="#java_pgcpp">premature garbage collection prevention
26970
parameter</A> (the 2nd and 4th parameters in the JNI calls).</LI>
26971
</UL>
25742
26972
<H2><A name="java_directors_faq"></A>20.10 Living with Java Directors</H2>
25743
26973
<P> This section is intended to address frequently asked questions and
25744
26974
frequently encountered problems when using Java directors.</P>
26074
27304
SWIG installation went well Unix users should be able to type <TT>make</TT>
26075
27305
in each example directory, then <TT>java main</TT> to see them running.
26076
27306
For the benefit of Windows users, there are also Visual C++ project
26077
files in a couple of the <A href="#examples">Windows Examples</A>.</P>
27307
files in a couple of the <A href="Windows.html#examples">Windows
27308
Examples</A>.</P>
26078
27309
<HR NOSHADE>
26079
27310
<H1><A name="Lisp_nn1"></A>21 SWIG and Common Lisp</H1>
26080
27311
26087
27318
<LI><A href="#Lisp_nn4">Additional Commandline Options</A></LI>
26088
27319
<LI><A href="#Lisp_nn5">Generating CFFI bindings</A></LI>
26089
27320
<LI><A href="#Lisp_nn6">Generating CFFI bindings for C++ code</A></LI>
27321
<LI><A href="#Lisp_nn7">Inserting user code into generated files</A></LI>
26090
27322
</UL>
26091
27323
</LI>
26092
<LI><A href="#Lisp_nn7">CLISP</A>
27324
<LI><A href="#Lisp_nn8">CLISP</A>
26093
27325
<UL>
26094
<LI><A href="#Lisp_nn8">Additional Commandline Options</A></LI>
26095
<LI><A href="#Lisp_nn9">Details on CLISP bindings</A></LI>
27326
<LI><A href="#Lisp_nn9">Additional Commandline Options</A></LI>
27327
<LI><A href="#Lisp_nn10">Details on CLISP bindings</A></LI>
26096
27328
</UL>
26097
27329
</LI>
26098
<LI><A href="#Lisp_nn10">UFFI</A></LI>
27330
<LI><A href="#Lisp_nn11">UFFI</A></LI>
26099
27331
</UL>
26100
27332
</DIV>
26101
27333
<!-- INDEX -->
26293
27525
function names for corresponding C function names, or you just want to
26294
27526
lispify the names, also, before we forget you want to export the
26295
27527
generated lisp names. To do this, we will use the SWIG <A href="#features">
26296
feature directive</A>. Lets edit the interface file such that the C type
26297
"div_t*" is changed to Lisp type ":my-pointer", we lispify all names,
26298
export everything, and do some more stuff.</P>
27528
feature directive</A>. Let's edit the interface file such that the C
27529
type "div_t*" is changed to Lisp type ":my-pointer", we lispify all
27530
names, export everything, and do some more stuff.</P>
26299
27531
<DIV class="code">
26300
27532
<PRE>
26301
27533
%module test
26574
27806
<P> If you have any questions, suggestions, patches, etc., related to
26575
27807
CFFI module feel free to contact us on the SWIG mailing list, and also
26576
27808
please add a "[CFFI]" tag in the subject line.</P>
26577
<H2><A name="Lisp_nn7"></A>21.3 CLISP</H2>
27809
<H3><A name="Lisp_nn7"></A>21.2.4 Inserting user code into generated
27810
files</H3>
27811
<P> It is often necessary to <A href="#SWIG_nn40">include user-defined
27812
code</A> into the automatically generated interface files. For example,
27813
when building a C++ interface, example_wrap.cxx will likely not compile
27814
unless you add a <TT>#include "header.h"</TT> directive. This can be
27815
done using the SWIG <TT>%insert(section) %{ ...code... %}</TT>
27816
directive:</P>
27817
<DIV class="code">
27818
<PRE>
27819
%module example
27820
27821
%insert("runtime") %{
27822
#include "header.h"
27823
%}
27824
27825
%include "header.h"
27826
27827
int fact(int n);
27828
</PRE>
27829
</DIV>
27830
<P> Additional sections have been added for inserting into the generated
27831
lisp interface file:</P>
27832
<UL>
27833
<LI><TT>lisphead</TT> - inserts before type declarations</LI>
27834
<LI><TT>swiglisp</TT> - inserts after type declarations according to
27835
where it appears in the .i file</LI>
27836
</UL>
27837
<P> Note that the block <TT>%{ ... %}</TT> is effectively a shortcut for
27838
<TT>%insert("runtime") %{ ... %}</TT>.</P>
27839
<H2><A name="Lisp_nn8"></A>21.3 CLISP</H2>
26578
27840
<P> <A href="http://clisp.cons.org">CLISP</A> is a feature-loaded
26579
27841
implementation of common lisp which is portable across most of the
26580
27842
operating system environments and hardware. CLISP includes an
26596
27858
modify them. The good thing is that you don't need to complex interface
26597
27859
file for the CLISP module. The CLISP module tries to produce code which
26598
27860
is both human readable and easily modifyable.</P>
26599
<H3><A name="Lisp_nn8"></A>21.3.1 Additional Commandline Options</H3>
27861
<H3><A name="Lisp_nn9"></A>21.3.1 Additional Commandline Options</H3>
26600
27862
<P> The following table list the additional commandline options
26601
27863
available for the CLISP module. They can also be seen by using:</P>
26602
27864
<DIV class="code">
26615
27877
def-c-type will be used to generate
26616
27878
<BR> shortcuts according to the typedefs in the input.</TD></TR>
26617
27879
</TABLE>
26618
<H3><A name="Lisp_nn9"></A>21.3.2 Details on CLISP bindings</H3>
27880
<H3><A name="Lisp_nn10"></A>21.3.2 Details on CLISP bindings</H3>
26619
27881
<P> As mentioned earlier the CLISP bindings generated by SWIG may need
26620
27882
some modifications. The clisp module creates a lisp file with the same
26621
27883
name as the module name. This lisp file contains a 'defpackage'
26733
27995
26734
27996
</PRE>
26735
27997
</DIV>
26736
<H2><A name="Lisp_nn10"></A>21.4 UFFI</H2>
27998
<H2><A name="Lisp_nn11"></A>21.4 UFFI</H2>
26737
27999
<HR NOSHADE>
26738
28000
<H1><A name="Lua_nn1"></A>22 SWIG and Lua</H1>
26739
28001
26764
28026
<LI><A href="#Lua_nn19">Class extension with %extend</A></LI>
26765
28027
<LI><A href="#Lua_nn20">C++ templates</A></LI>
26766
28028
<LI><A href="#Lua_nn21">C++ Smart Pointers</A></LI>
28029
<LI><A href="#Lua_nn22">Writing your own custom wrappers</A></LI>
26767
28030
</UL>
26768
28031
</LI>
26769
<LI><A href="#Lua_nn22">Details on the Lua binding</A>
28032
<LI><A href="#Lua_nn23">Details on the Lua binding</A>
26770
28033
<UL>
26771
<LI><A href="#Lua_nn23">Binding global data into the module.</A></LI>
26772
<LI><A href="#Lua_nn24">Userdata and Metatables</A></LI>
26773
<LI><A href="#Lua_nn25">Memory management</A></LI>
28034
<LI><A href="#Lua_nn24">Binding global data into the module.</A></LI>
28035
<LI><A href="#Lua_nn25">Userdata and Metatables</A></LI>
28036
<LI><A href="#Lua_nn26">Memory management</A></LI>
26774
28037
</UL>
26775
28038
</LI>
26776
28039
</UL>
26787
28050
binary code. It can be found at <A href="http://www.lua.org">
26788
28051
http://www.lua.org</A></P>
26789
28052
<H2><A name="Lua_nn2"></A>22.1 Preliminaries</H2>
26790
<P> The current SWIG implementation is designed to work with Lua 5.0. It
26791
should work with later versions of Lua, but certainly not with Lua 4.0
26792
due to substantial API changes. ((Currently SWIG generated code has
26793
only been tested on Windows with MingW, though given the nature of Lua,
26794
is should not have problems on other OS's)). It is possible to either
26795
static link or dynamic link a Lua module into the interpreter (normally
26796
Lua static links its libraries, as dynamic linking is not available on
26797
all platforms).</P>
26798
<P> Note: Lua 5.1 (alpha) has just (as of September 05) been released.
26799
The current version of SWIG will produce wrappers which are compatible
26800
with Lua 5.1, though the dynamic loading mechanism has changed (see
26801
below). The configure script and makefiles should work correctly with
26802
with Lua 5.1, though some small tweaks may be needed.</P>
28053
<P> The current SWIG implementation is designed to work with Lua 5.0.x
28054
and Lua 5.1.x. It should work with later versions of Lua, but certainly
28055
not with Lua 4.0 due to substantial API changes. ((Currently SWIG
28056
generated code has only been tested on Windows with MingW, though given
28057
the nature of Lua, is should not have problems on other OS's)). It is
28058
possible to either static link or dynamic link a Lua module into the
28059
interpreter (normally Lua static links its libraries, as dynamic
28060
linking is not available on all platforms).</P>
26803
28061
<H2><A name="Lua_nn3"></A>22.2 Running SWIG</H2>
26804
28062
<P> Suppose that you defined a SWIG module such as the following:</P>
26805
28063
<DIV class="code">
26832
28090
file. For example, if the input file is <TT>example.i</TT>, the name of
26833
28091
the wrapper file is <TT>example_wrap.c</TT>. To change this, you can
26834
28092
use the -o option. The wrappered module will export one function <TT>
26835
"int Example_Init(LuaState* L)"</TT> which must be called to register
26836
the module with the Lua interpreter. The name "Example_Init" depends
26837
upon the name of the module. Note: SWIG will automatically capitalise
26838
the module name, so <TT>"module example;"</TT> becomes <TT>
26839
"Example_Init"</TT>.</P>
28093
"int luaopen_example(LuaState* L)"</TT> which must be called to register
28094
the module with the Lua interpreter. The name "luaopen_example" depends
28095
upon the name of the module.</P>
26840
28096
<H3><A name="Lua_nn4"></A>22.2.1 Compiling and Linking and Interpreter</H3>
26841
28097
<P> Normally Lua is embedded into another program and will be statically
26842
28098
linked. An extremely simple stand-alone interpreter (<TT>min.c</TT>) is
26848
28104
#include "lualib.h"
26849
28105
#include "lauxlib.h"
26850
28106
26851
extern int Example_Init(LuaState* L); // declare the wrapped module
28107
extern int luaopen_example(LuaState* L); // declare the wrapped module
26852
28108
26853
28109
int main(int argc,char* argv[])
26854
28110
{
26855
28111
lua_State *L;
26856
if (argc
26857
<!--2)
28112
if (argc<2)
26858
28113
{
26859
28114
printf("%s: <filename.lua>\n",argv[0]);
26860
28115
return 0;
26861
28116
}
26862
28117
L=lua_open();
26863
28118
luaopen_base(L); // load basic libs (eg. print)
26864
Example_Init(L); // load the wrappered module
28119
luaopen_example(L); // load the wrappered module
26865
28120
if (luaL_loadfile(L,argv[1])==0) // load and run the file
26866
28121
lua_pcall(L,0,0,0);
26867
28122
else
26869
28124
lua_close(L);
26870
28125
return 0;
26871
28126
}
26872
</pre-->
26873
28127
</PRE>
26874
28128
</DIV>
26875
28129
<P> A much improved set of code can be found in the Lua distribution <TT>
26876
28130
src/lua/lua.c</TT>. Include your module, just add the external
26877
declaration & add a <TT>#define LUA_EXTRALIBS {"example",Example_Init}</TT>
26878
, at the relevant place.</P>
28131
declaration & add a <TT>#define LUA_EXTRALIBS
28132
{"example",luaopen_example}</TT>, at the relevant place.</P>
26879
28133
<P> The exact commands for doing this vary from platform to platform.
26880
28134
Here is a possible set of commands of doing this:</P>
26881
28135
<DIV class="shell">
26900
28154
$ gcc -shared -I/usr/include/lua -L/usr/lib/lua example_wrap.o example.o -o example.so
26901
28155
</PRE>
26902
28156
</DIV>
26903
<P> You will also need an interpreter with the loadlib function (such as
26904
the default interpreter compiled with Lua). In order to dynamically
26905
load a module you must call the loadlib function with two parameters:
26906
the filename of the shared library, and the function exported by SWIG.
26907
Calling loadlib should return the function, which you then call to
26908
initialise the module</P>
26909
<DIV class="targetlang">
26910
<PRE>
26911
my_init=loadlib("example.so","Example_Init") -- for Unix/Linux
26912
--my_init=loadlib("example.dll","Example_Init") -- for Windows
28157
<P> The wrappers produced by SWIG can be compiled and linked with Lua
28158
5.1.x. The loading is extremely simple.</P>
28159
<DIV class="targetlang">
28160
<PRE>
28161
require("example")
28162
</PRE>
28163
</DIV>
28164
<P> For those using Lua 5.0.x, you will also need an interpreter with
28165
the loadlib function (such as the default interpreter compiled with
28166
Lua). In order to dynamically load a module you must call the loadlib
28167
function with two parameters: the filename of the shared library, and
28168
the function exported by SWIG. Calling loadlib should return the
28169
function, which you then call to initialise the module</P>
28170
<DIV class="targetlang">
28171
<PRE>
28172
my_init=loadlib("example.so","luaopen_example") -- for Unix/Linux
28173
--my_init=loadlib("example.dll","luaopen_example") -- for Windows
26913
28174
assert(my_init) -- name sure its not nil
26914
28175
my_init() -- call the init fn of the lib
26915
28176
</PRE>
26917
28178
<P> Or can be done in a single line of Lua code</P>
26918
28179
<DIV class="targetlang">
26919
28180
<PRE>
26920
assert(loadlib("example.so","Example_Init"))()
26921
</PRE>
26922
</DIV>
26923
<P> Update for Lua 5.1 (alpha):
26924
<BR> The wrappers produced by SWIG can be compiled and linked with Lua
26925
5.1. The loading is now much simpler.</P>
26926
<DIV class="targetlang">
26927
<PRE>
26928
require("example")
28181
assert(loadlib("example.so","luaopen_example"))()
26929
28182
</PRE>
26930
28183
</DIV>
26931
28184
<P> If the code didn't work, don't panic. The best thing to do is to
26934
28187
all this code is case sensitive).</P>
26935
28188
<DIV class="targetlang">
26936
28189
<PRE>
26937
a,b,c=loadlib("example.so","Example_Init") -- for Unix/Linux
26938
--a,b,c=loadlib("example.dll","Example_Init") -- for Windows
28190
a,b,c=package.loadlib("example.so","luaopen_example") -- for Unix/Linux
28191
--a,b,c=package.loadlib("example.dll","luaopen_example") -- for Windows
26939
28192
print(a,b,c)
26940
28193
</PRE>
26941
28194
</DIV>
26942
<P> Note: for Lua 5.1:
26943
<BR> The loadlib() function has been moved into the package table, so
26944
you must use package.loadlib() instead.</P>
28195
<P> Note: for Lua 5.0:
28196
<BR> The loadlib() function is in the global namespace, not in package.
28197
So its just loadlib().</P>
26945
28198
<P> if 'a' is a function, this its all working fine, all you need to do
26946
28199
is call it</P>
26947
28200
<DIV class="targetlang">
27037
28290
extern double Foo;
27038
28291
</PRE>
27039
28292
</DIV>
27040
<P> SWIG will actually generate two functions <TT>example.Foo_set()</TT>
28293
<P> SWIG will effectively generate two functions <TT>example.Foo_set()</TT>
27041
28294
and <TT>example.Foo_get()</TT>. It then adds a metatable to the table
27042
28295
'example' to call these functions at the correct time (when you attempt
27043
28296
to set or get examples.Foo). Therefore if you were to attempt to assign
27069
28322
4
27070
28323
</PRE>
27071
28324
</DIV>
27072
<P> If a variable is marked with the immutable directive then any
27073
attempts to set this variable are silently ignored.</P>
27074
<P> Another interesting feature is that it is not possible to add new
27075
values into the module from within the interpreter, this is because of
27076
the metatable to deal with global variables. It is possible (though not
27077
recommended) to use rawset() to add a new value.</P>
28325
<P> If a variable is marked with the %immutable directive then any
28326
attempts to set this variable will cause an lua error. Given a global
28327
variable:</P>
28328
<DIV class="code">
28329
<PRE>%module example
28330
%immutable;
28331
extern double Foo;
28332
%mutable;
28333
</PRE>
28334
</DIV>
28335
<P> SWIG will allow the the reading of <TT>Foo</TT> but when a set
28336
attempt is made, an error function will be called.</P>
28337
<DIV class="targetlang">
28338
<PRE>
28339
> print(e.Foo) -- reading works ok
28340
4
28341
> example.Foo=40 -- but writing does not
28342
This variable is immutable
28343
stack traceback:
28344
[C]: ?
28345
[C]: ?
28346
stdin:1: in main chunk
28347
[C]: ?
28348
</PRE>
28349
</DIV>
28350
<P> For those people who would rather that SWIG silently ignore the
28351
setting of immutables (as previous versions of the lua bindings did),
28352
adding a <TT>-DSWIGLUA_IGNORE_SET_IMMUTABLE</TT> compile option will
28353
remove this.</P>
28354
<P> Unlike earlier versions of the binding, it is now possible to add
28355
new functions or variables to the module, just as if it were a normal
28356
table. This also allows the user to rename/remove existing functions
28357
and constants (but not linked variables, mutable or immutable).
28358
Therefore users are recommended to be careful when doing so.</P>
27078
28359
<DIV class="targetlang">
27079
28360
<PRE>
27080
28361
> -- example.PI does not exist
27081
28362
> print(example.PI)
27082
28363
nil
27083
> example.PI=3.142 -- assign failed, example.PI does still not exist
27084
> print(example.PI)
27085
nil
27086
> -- a rawset will work, after this the value is added
27087
> rawset(example,"PI",3.142)
28364
> example.PI=3.142 -- new value added
27088
28365
> print(example.PI)
27089
28366
3.142
27090
28367
</PRE>
27147
28424
> print(f)
27148
28425
userdata: 003FDA80
27149
28426
> print(swig_type(f))
27150
_p_FILE -- its a FILE*
28427
FILE * -- its a FILE*
27151
28428
</PRE>
27152
28429
</DIV>
27153
28430
<P> Lua enforces the integrity of its userdata, so it is virtually
27176
28453
<P> is used as follows:</P>
27177
28454
<DIV class="targetlang">
27178
28455
<PRE>
27179
> p=example.Point()
28456
> p=example.new_Point()
27180
28457
> p.x=3
27181
28458
> p.y=5
27182
28459
> print(p.x,p.y)
27186
28463
</DIV>
27187
28464
<P> Similar access is provided for unions and the data members of C++
27188
28465
classes.
27189
<BR> SWIG will also create a function <TT>new_Point()</TT> which also
27190
creates a new Point structure.</P>
28466
<BR> C structures are created using a function <TT>new_Point()</TT>, but
28467
for C++ classes are created using just the name <TT>Point()</TT>.</P>
27191
28468
<P> If you print out the value of p in the above example, you will see
27192
28469
something like this:</P>
27193
28470
<DIV class="targetlang">
27198
28475
</DIV>
27199
28476
<P> Like the pointer in the previous section, this is held as a
27200
28477
userdata. However, additional features have been added to make this
27201
more usable. SWIG creates some accessor/mutator functions <TT>
27202
Point_set_x()</TT> and <TT>Point_get_x()</TT>. These will be wrappered,
27203
and then added to the metatable added to the userdata. This provides
27204
the natural access to the member variables that were shown above (see
27205
end of the document for full details).</P>
28478
more usable. SWIG effectivly creates some accessor/mutator functions to
28479
get and set the data. These functions will be added to the userdata's
28480
metatable. This provides the natural access to the member variables
28481
that were shown above (see end of the document for full details).</P>
27206
28482
<P> <TT>const</TT> members of a structure are read-only. Data members
27207
28483
can also be forced to be read-only using the immutable directive. As
27208
with other immutable's, setting attempts will be silently ignored. For
28484
with other immutable's, setting attempts will be cause an error. For
27209
28485
example:</P>
27210
28486
<DIV class="code">
27211
28487
<PRE>struct Foo {
27309
28585
<P> In Lua, the static members can be accessed as follows:</P>
27310
28586
<DIV class="code">
27311
28587
<PRE>
27312
> example.Spam_foo() -- Spam::foo() the only way currently
27313
> a=example.Spam_bar_get() -- Spam::bar the hard way
27314
> a=example.Spam_bar -- Spam::bar the nicer way
27315
> example.Spam_bar_set(b) -- Spam::bar the hard way
27316
> example.Spam_bar=b -- Spam::bar the nicer way
28588
> example.Spam_foo() -- calling Spam::foo()
28589
> a=example.Spam_bar -- reading Spam::bar
28590
> example.Spam_bar=b -- writing to Spam::bar
27317
28591
</PRE>
27318
28592
</DIV>
27319
28593
<P> It is not (currently) possible to access static members of an
27759
29033
> f = p:__deref__() -- Returns underlying Foo *
27760
29034
</PRE>
27761
29035
</DIV>
27762
<H2><A name="Lua_nn22"></A>22.4 Details on the Lua binding</H2>
29036
<H3><A name="Lua_nn22"></A>22.3.15 Writing your own custom wrappers</H3>
29037
<P> Sometimes, it may be neccesary to add your own special functions,
29038
which bypass the normal SWIG wrappering method, and just use the native
29039
lua-c API calls. These 'native' functions allow direct adding of your
29040
own code into the module. This is performed with the <TT>%native</TT>
29041
directive as follows:</P>
29042
<DIV class="code">
29043
<PRE>%native(my_func) int native_function(lua_State*L); // registers it with SWIG
29044
...
29045
%{
29046
int native_function(lua_State*L) // my native code
29047
{
29048
...
29049
}
29050
%}
29051
</PRE>
29052
</DIV>
29053
<P> The <TT>%native</TT> directive in the above example, tells SWIG that
29054
there is a function <TT>int native_function(lua_State*L);</TT> which is
29055
to be added into the module under the name '<TT>my_func</TT>'. SWIG
29056
will not add any wrappering for this function, beyond adding it into
29057
the function table. How you write your code is entirely up to you.</P>
29058
<H2><A name="Lua_nn23"></A>22.4 Details on the Lua binding</H2>
27763
29059
<P> In the previous section, a high-level view of Lua wrapping was
27764
29060
presented. Obviously a lot of stuff happens behind the scenes to make
27765
29061
this happen. This section will explain some of the low-level details on
27768
29064
stop reading here. This is going into the guts of the code and how it
27769
29065
works. Its mainly for people who need to know whats going on within the
27770
29066
code.</I></P>
27771
<H3><A name="Lua_nn23"></A>22.4.1 Binding global data into the module.</H3>
29067
<H3><A name="Lua_nn24"></A>22.4.1 Binding global data into the module.</H3>
27772
29068
<P> Assuming that you had some global data that you wanted to share
27773
29069
between C and Lua. How does SWIG do it?</P>
27774
29070
<DIV class="code">
27784
29080
</DIV>
27785
29081
<P> At initialisation time, it will then add to the interpreter a table
27786
29082
called 'example', which represents the module. It will then add all its
27787
functions to the module. But it also adds a metatable to this table,
27788
which has two functions (<TT>__index</TT> and <TT>__newindex</TT>) as
27789
well as two tables (<TT>.get</TT> and <TT>.set</TT>) The following Lua
27790
code will show these hidden features.</P>
29083
functions to the module. (Note: older versions of SWIG actually added
29084
the Foo_set() and Foo_get() functions, current implementation does not
29085
add these functions and more.) But it also adds a metatable to this
29086
table, which has two functions (<TT>__index</TT> and <TT>__newindex</TT>
29087
) as well as two tables (<TT>.get</TT> and <TT>.set</TT>) The following
29088
Lua code will show these hidden features.</P>
27791
29089
<DIV class="targetlang">
27792
29090
<PRE>
27793
29091
> print(example)
27824
29122
if not s then return end
27825
29123
local f=s[name] -- looks for the function
27826
29124
-- calls it to set the value
27827
if type(f)=="function" then f(value) end
29125
if type(f)=="function" then f(value)
29126
else rawset(mod,name,value) end
27828
29127
end
27829
29128
</PRE>
27830
29129
</DIV>
27835
29134
'Foo_get()'. Similarly for the code '<TT>example.Foo=10</TT>', the
27836
29135
interpreter will check the table, then call the __newindex which will
27837
29136
then check the '.set' table and call the C function 'Foo_set(10)'.</P>
27838
<H3><A name="Lua_nn24"></A>22.4.2 Userdata and Metatables</H3>
29137
<H3><A name="Lua_nn25"></A>22.4.2 Userdata and Metatables</H3>
27839
29138
<P> As mentioned earlier, classes and structures, are all held as
27840
29139
pointer, using the Lua 'userdata' structure. This structure is actually
27841
29140
a pointer to a C structure 'swig_lua_userdata', which contains the
27888
29187
.fn table: 003FB528
27889
29188
</PRE>
27890
29189
</DIV>
27891
<P> The '.type' attribute is the string which is returned from a call to
27892
swig_type(). The '.get' and '.set' tables work in a similar manner to
27893
the modules, the main difference is the '.fn' table which also holds
27894
all the member functions. (The '__gc' function is the classes
27895
destructor function)</P>
29190
<P> The '.type' attribute is the name of the class. The '.get' and
29191
'.set' tables work in a similar manner to the modules, the main
29192
difference is the '.fn' table which also holds all the member
29193
functions. (The '__gc' function is the classes destructor function)</P>
27896
29194
<P> The Lua equivalent of the code for enabling functions looks a little
27897
29195
like this</P>
27898
29196
<DIV class="targetlang">
27933
29231
The current implementation is a bit rough as it will add any member
27934
29232
function beginning with '__' into the metatable too, assuming its an
27935
29233
operator overload.</P>
27936
<H3><A name="Lua_nn25"></A>22.4.3 Memory management</H3>
29234
<H3><A name="Lua_nn26"></A>22.4.3 Memory management</H3>
27937
29235
<P> Lua is very helpful with the memory management. The
27938
29236
'swig_lua_userdata' is fully managed by the interpreter itself. This
27939
29237
means that neither the C code nor the Lua code can damage it. Once a
29920
31218
</DIV>
29921
31219
<P> The <TT>%immutable</TT> directive stays in effect until it is
29922
31220
explicitly disabled or cleared using <TT>%mutable</TT>. See the <A href="#SWIG_readonly_variables">
29923
Creatng read-only variables</A> section for further details.</P>
31221
Creating read-only variables</A> section for further details.</P>
29924
31222
<P> It is also possible to tag a specific variable as read-only like
29925
31223
this:</P>
29926
31224
<DIV class="code">
31517
32815
{
31518
32816
my ($im, $x) = @_;
31519
32817
my $a = new_mat44();
31520
for (my $i = 0; $i <4, $i++)
32818
for (my $i = 0; $i < 4, $i++)
31521
32819
{
31522
for (my $j = 0; $j <4, $j++)
32820
for (my $j = 0; $j < 4, $j++)
31523
32821
{
31524
32822
mat44_set($a, $i, $j, $x->[i][j])
31525
32823
}
31615
32913
<P> Swig can generate PHP extensions from C++ libraries as well when
31616
32914
given the <TT>-c++</TT> option. The support for C++ is discussed in
31617
32915
more detail in <A href="#Php_nn2_6">section 27.2.6</A>.</P>
31618
<P> To finish building the extension, you have two choices. The usual
31619
way is to build the extension as a separate dynamically loaded module.
31620
You can then specify that this be loaded automatically in <TT>php.ini</TT>
31621
or load it explicitly for any script which needs it. The alternative to
31622
creating a dynamically loaded module is to rebuild the entire php
31623
source tree and build the extension into the php executable/library so
31624
it will be available in every script. The first choice is the default,
31625
however it can be changed by passing the '-phpfull' command line switch
31626
to swig to select the second build method.</P>
32916
<P> The usual (and recommended) way is to build the extension as a
32917
separate dynamically loaded module. You can then specify that this be
32918
loaded automatically in <TT>php.ini</TT> or load it explicitly for any
32919
script which needs it.</P>
32920
<P> It is also possible to rebuild PHP from source so that your module
32921
is statically linked into the php executable/library. This is a lot
32922
more work, and also requires a full rebuild of PHP to update your
32923
module, and it doesn't play nicely with package system. We don't
32924
recommend this approach, but if you really want to do this, the <TT>
32925
-phpfull</TT> command line argument to swig may be of use - see below
32926
for details.</P>
31627
32927
<H3><A name="Php_nn1_1"></A>27.1.1 Building a loadable extension</H3>
31628
<P> There are two methods to build the extension as a dynamically loaded
31629
module: using standard compilation utilities (make, gcc), or using
31630
PHP's<EM> phpize</EM> utility.</P>
31631
<P> To build manually, use a compile string similar to this (different
31632
for each OS):</P>
32928
<P> To build your module as a dynamically loadable extension, use
32929
compilation commands like these (if you aren't using GCC, the commands
32930
will be different, and there may be so variation between platforms -
32931
these commands should at least work for Linux though):</P>
31633
32932
<DIV class="code">
31634
32933
<PRE>
31635
cc -I.. $(PHPINC) -fpic -c example_wrap.c
31636
cc -shared example_wrap.o -o example.so
32934
gcc `php-config --includes` -fpic -c example_wrap.c
32935
gcc -shared example_wrap.o -o example.so
31637
32936
</PRE>
31638
32937
</DIV>
31639
<P> The <TT>-make</TT> command line argument to swig will generate an
31640
additional file <TT>Makefile</TT> which can usually build the extension
31641
itself (on UNIX platforms).</P>
31642
<P> If you want to build your extension using the <TT>phpize</TT>
31643
utility, or if you want to build your module into PHP directly, you can
31644
specify the <TT>-phpfull</TT> command line argument to swig.</P>
31645
<P> The <TT>-phpfull</TT> will generate three additional files. The
31646
first extra file, <TT>config.m4</TT> contains the shell code needed to
31647
enable the extension as part of the PHP build process. The second extra
31648
file, <TT>Makefile.in</TT> contains the information needed to build the
31649
final Makefile after substitutions. The third and final extra file, <TT>
31650
CREDITS</TT> should contain the credits for the extension.</P>
32938
<P> There is a deprecated <TT>-make</TT> command line argument to swig
32939
which will generate an additional file <TT>makefile</TT> which can
32940
usually build the extension (at least on some UNIX platforms), but the
32941
Makefile generated isn't very flexible, and the commands required are
32942
trivial so it is simpler to just add them to your Makefile or other
32943
build system directly. We recommend that you don't use <TT>-make</TT>
32944
and it's likely to be removed at some point.</P>
32945
<H3><A name="Php_nn1_2"></A>27.1.2 Building extensions into PHP</H3>
32946
<P> Note that we don't recommend this approach - it's cleaner and
32947
simpler to use dynamically loadable modules, which are supported by all
32948
modern OSes. Support for this may be discontinued entirely in the
32949
future.</P>
32950
<P> It is possible to rebuild PHP itself with your module statically
32951
linked in. To do this, you can use the <TT>-phpfull</TT> command line
32952
option to swig. Using this option will generate three additional files.
32953
The first extra file, <TT>config.m4</TT> contains the m4 and shell code
32954
needed to enable the extension as part of the PHP build process. The
32955
second extra file, <TT>Makefile.in</TT> contains the information needed
32956
to build the final Makefile after substitutions. The third and final
32957
extra file, <TT>CREDITS</TT> should contain the credits for the
32958
extension.</P>
31651
32959
<P> To build with phpize, after you have run swig you will need to run
31652
32960
the 'phpize' command (installed as part of php) in the same directory.
31653
32961
This re-creates the php build environment in that directory. It also
31680
32988
extension. The extension object file will be left in the modules sub
31681
32989
directory, you can move it to wherever it is convenient to call from
31682
32990
your php script.</P>
31683
<P> Both the <TT>-make</TT> and <TT>-phpfull</TT> arguments accept
32991
<P> When using <TT>-phpfull</TT>, swig also accepts the following
31684
32992
additional optional arguments:</P>
31685
32993
<UL>
31686
32994
<LI><TT>-withincs "<incs>"</TT> Adds include files to the config.m4
31687
32995
file.</LI>
31688
<LI><TT>-withlibs "<libs>"</TT> Links the libraries into the shared
31689
object.</LI>
31690
<LI><TT>-withc "<files>"</TT> Compiles and links the named C files into
31691
the shared object.</LI>
31692
<LI><TT>-withcxx "<files>"</TT> Compiles and links the named C++ files
31693
into the shared object,</LI>
32996
<LI><TT>-withlibs "<libs>"</TT> Links with the specified libraries.</LI>
32997
<LI><TT>-withc "<files>"</TT> Compiles and links the additional
32998
specified C files.</LI>
32999
<LI><TT>-withcxx "<files>"</TT> Compiles and links the additional
33000
specified C++ files.</LI>
31694
33001
</UL>
31695
<H3><A name="Php_nn1_2"></A>27.1.2 Building extensions into PHP</H3>
31696
<P> This method, selected with the <TT>-phpfull</TT> command line
31697
switch, involves rebuilding the entire php source tree. Whilst more
31698
complicated to build, it does mean that the extension is then available
31699
without having to load it in each script.</P>
31700
33002
<P> After running swig with the <TT>-phpfull</TT> switch, you will be
31701
33003
left with a shockingly similar set of files to the previous build
31702
33004
process. However you will then need to move these files to a
32100
33402
additional php code is generated. For PHP5, a PHP wrapper class is
32101
33403
generated which calls a set of flat functions wrapping the C++ class.
32102
33404
In many cases the PHP4 and PHP5 wrappers will behave the same way, but
32103
the PHP5 ones make use of better PHP5's better OO funcationality where
33405
the PHP5 ones make use of better PHP5's better OO functionality where
32104
33406
appropriate.</P>
32105
33407
<P> This interface file</P>
32106
33408
<DIV class="code">
32505
33807
<LI><A href="#Python_nn3">Preliminaries</A>
32506
33808
<UL>
32507
33809
<LI><A href="#Python_nn4">Running SWIG</A></LI>
32508
<LI><A href="#Python_nn6">Compiling a dynamic module</A></LI>
32509
<LI><A href="#Python_nn7">Using distutils</A></LI>
33810
<LI><A href="#Python_nn6">Using distutils</A></LI>
33811
<LI><A href="#Python_nn7">Hand compiling a dynamic module</A></LI>
32510
33812
<LI><A href="#Python_nn8">Static linking</A></LI>
32511
33813
<LI><A href="#Python_nn9">Using your module</A></LI>
32512
33814
<LI><A href="#Python_nn10">Compilation of C++ extensions</A></LI>
32637
33939
<DIV class="code">
32638
33940
<PRE>
32639
33941
/* File: example.i */
32640
%module test
33942
%module example
33943
32641
33944
%{
32642
#include "stuff.h"
33945
#define SWIG_FILE_WITH_INIT
33946
#include "example.h"
32643
33947
%}
32644
int fact(int n);
32645
</PRE>
32646
</DIV>
32647
<P> To build a Python module, run SWIG using the <TT>-python</TT> option
32648
:</P>
33948
33949
int fact(int n);
33950
</PRE>
33951
</DIV>
33952
<P> The <TT>#define SWIG_FILE_WITH_INIT</TT> line inserts a macro that
33953
specifies that the resulting C file should be built as a python
33954
extension, inserting the module <TT>init</TT> code. This <TT>.i</TT>
33955
file wraps the following simple C file:</P>
33956
<DIV class="code">
33957
<PRE>
33958
/* File: example.c */
33959
33960
#include "example.h"
33961
33962
int fact(int n) {
33963
if (n < 0){ /* This should probably return an error, but this is simpler */
33964
return 0;
33965
}
33966
if (n == 0) {
33967
return 1;
33968
}
33969
else {
33970
/* testing for overflow would be a good idea here */
33971
return n * fact(n-1);
33972
}
33973
}
33974
33975
</PRE>
33976
</DIV>
33977
<P> With the header file:</P>
33978
<DIV class="code">
33979
<PRE>
33980
/* File: example.h */
33981
33982
int fact(int n);
33983
</PRE>
33984
</DIV>
33985
<P> To build a Python module, run SWIG using the <TT>-python</TT>
33986
option:</P>
32649
33987
<DIV class="shell">
32650
33988
<PRE>
32651
33989
$ swig -python example.i
32672
34010
example</TT>, then a file <TT>example.py</TT> is created.</P>
32673
34011
<P> The following sections have further practical examples and details
32674
34012
on how you might go about compiling and using the generated files.</P>
32675
<DIV class="diagram">
32676
<PRE>
32677
/usr/local/include/python2.0
32678
</PRE>
32679
</DIV>
32680
<P> The exact location may vary on your machine, but the above location
32681
is typical. If you are not entirely sure where Python is installed, you
32682
can run Python to find out. For example:</P>
32683
<DIV class="targetlang">
32684
<PRE>
32685
$ python
32686
Python 2.1.1 (#1, Jul 23 2001, 14:36:06)
32687
[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
32688
Type "copyright", "credits" or "license" for more information.
32689
>>> import sys
32690
>>> print sys.prefix
32691
/usr/local
32692
>>>
32693
</PRE>
32694
</DIV>
32695
<H3><A name="Python_nn6"></A>29.2.2 Compiling a dynamic module</H3>
32696
<P> The preferred approach to building an extension module is to compile
32697
it into a shared object file or DLL. To do this, you need to compile
32698
your program using commands like this (shown for Linux):</P>
34013
<H3><A name="Python_nn6"></A>29.2.2 Using distutils</H3>
34014
<P> The preferred approach to building an extension module for python is
34015
to compile it with distutils, which comes with all recent versions of
34016
python (<A href="http://docs.python.org/dist/dist.html">Distutils Docs</A>
34017
).</P>
34018
<P> Distutils takes care of making sure that your extension is built
34019
with all the correct flags, headers, etc. for the version of Python it
34020
is run with. Distutils will compile your extension into a shared object
34021
file or DLL (<TT>.so</TT> on Linux, <TT>.pyd</TT> on Windows, etc). In
34022
addition, distutils can handle installing your package into
34023
site-packages, if that is desired. A configuration file (conventionally
34024
called: <TT>setup.py</TT>) describes the extension (and related python
34025
modules). The distutils will then generate all the right compiler
34026
directives to build it for you.</P>
34027
<P> Here is a sample <TT>setup.py</TT> file for the above example:</P>
34028
<DIV class="code">
34029
<PRE>
34030
#!/usr/bin/env python
34031
34032
"""
34033
setup.py file for SWIG example
34034
"""
34035
34036
from distutils.core import setup, Extension
34037
34038
34039
example_module = Extension('_example',
34040
sources=['example_wrap.c', 'example.c'],
34041
)
34042
34043
setup (name = 'example',
34044
version = '0.1',
34045
author = "SWIG Docs",
34046
description = """Simple swig example from docs""",
34047
ext_modules = [example_module],
34048
py_modules = ["example"],
34049
)
34050
</PRE>
34051
</DIV>
34052
<P> In this example, the line: <TT>example_module = Extension(....)</TT>
34053
creates an Extension module object, defining the name as <TT>_example</TT>
34054
, and using the source code files: <TT>example_wrap.c</TT>, generated by
34055
swig, and <TT>example.c</TT>, your original c source. The swig (and
34056
other python extension modules) tradition is for the compiled extension
34057
to have the name of the python portion, prefixed by an underscore. If
34058
the name of your python module is "<TT>example.py</TT>", then the name
34059
of the corresponding object file will be"<TT>_example.so</TT>"</P>
34060
<P> The <TT>setup</TT> call then sets up distutils to build your
34061
package, defining some meta data, and passing in your extension module
34062
object. Once this is saved as <TT>setup.py</TT>, you can build your
34063
extension with these commands:</P>
34064
<DIV class="shell">
34065
<PRE>
34066
$ swig -python example.i
34067
$ python setup.py build_ext --inplace
34068
</PRE>
34069
</DIV>
34070
<P> And a .so, or .pyd or... will be created for you. It will build a
34071
version that matches the python that you run the command with. Taking
34072
apart the command line:</P>
34073
<UL>
34074
<LI> <TT>python</TT> -- the version of python you want to build for</LI>
34075
<LI> <TT>setup.py</TT> -- the name of your setup script (it can be
34076
called anything, but setup.py is the tradition)</LI>
34077
<LI> <TT>build_ext</TT> -- telling distutils to build extensions</LI>
34078
<LI> <TT>--inplace</TT> -- this tells distutils to put the extension lib
34079
in the current dir. Other wise, it will put it inside a build
34080
hierarchy, and you'd have to move it to use it.</LI>
34081
</UL>
34082
<P> The distutils have many other features, consult the python distutils
34083
docs for details.</P>
34084
<P> This same approach works on all platforms if the appropriate
34085
compiler is installed. (it can even build extensions to the standard
34086
Windows Python using MingGW)</P>
34087
<H3><A name="Python_nn7"></A>29.2.3 Hand compiling a dynamic module</H3>
34088
<P> While the preferred approach to building an extension module is to
34089
use the distutils, some people like to integrate building extensions
34090
with a larger build system, and thus may wish to compile their modules
34091
without the distutils. To do this, you need to compile your program
34092
using commands like this (shown for Linux):</P>
32699
34093
<DIV class="shell">
32700
34094
<PRE>
32701
34095
$ swig -python example.i
32726
34120
socket</TT> module actually consists of two files; <TT>socket.py</TT>
32727
34121
and <TT>_socket.so</TT>. Many other built-in Python modules follow a
32728
34122
similar convention.</P>
32729
<H3><A name="Python_nn7"></A>29.2.3 Using distutils</H3>
32730
34123
<H3><A name="Python_nn8"></A>29.2.4 Static linking</H3>
32731
34124
<P> An alternative approach to dynamic linking is to rebuild the Python
32732
34125
interpreter with your extension module added to it. In the past, this
32906
34299
<P> Compilation of C++ extensions has traditionally been a tricky
32907
34300
problem. Since the Python interpreter is written in C, you need to take
32908
34301
steps to make sure C++ is properly initialized and that modules are
32909
compiled correctly.</P>
34302
compiled correctly. This should be a non-issue if you're using
34303
distutils, as it takes care of all that for you. The following is
34304
included for historical reasons, and in case you need to compile on
34305
your own.</P>
32910
34306
<P> On most machines, C++ extension modules should be linked using the
32911
34307
C++ compiler. For example:</P>
32912
34308
<DIV class="shell">
33005
34401
<H3><A name="Python_nn12"></A>29.2.8 Building Python Extensions under
33006
34402
Windows</H3>
33007
34403
<P> Building a SWIG extension to Python under Windows is roughly similar
33008
to the process used with Unix. You will need to create a DLL that can
33009
be loaded into the interpreter. This section briefly describes the use
33010
of SWIG with Microsoft Visual C++. As a starting point, many of SWIG's
33011
examples include project files. You might want to take a quick look at
33012
these in addition to reading this section.</P>
34404
to the process used with Unix. Using the distutils, it is essentially
34405
identical. If you have the same version of the MS compiler that Python
34406
was built with (the python2.4 and python2.5 distributed by python.org
34407
are built with Visual Studio 2003), the standard <TT>python setup.py
34408
build</TT> should just work.</P>
34409
<P> As of python2.5, the distutils support building extensions with
34410
MingGW out of the box. Following the instruction here: <A href="http://boodebr.org/main/python/build-windows-extensions">
34411
Building Python extensions for Windows with only free tools</A> should
34412
get you started.</P>
34413
<P> If you need to build it on your own, the following notes are
34414
provided:</P>
34415
<P> You will need to create a DLL that can be loaded into the
34416
interpreter. This section briefly describes the use of SWIG with
34417
Microsoft Visual C++. As a starting point, many of SWIG's examples
34418
include project files. You might want to take a quick look at these in
34419
addition to reading this section.</P>
33013
34420
<P> In Developer Studio, SWIG should be invoked as a custom build
33014
34421
option. This is usually done as follows:</P>
33015
34422
<UL>
34586
35993
references, such as<DIV class="code">
34587
35994
<PRE>
34588
35995
class Foo {
34589
&hellip;
35996
…
34590
35997
virtual const int& bar();
34591
&hellip;
35998
…
34592
35999
};
34593
36000
</PRE>
34594
36001
</DIV></P>
34600
36007
<DIV class="code">
34601
36008
<PRE>
34602
36009
class Foo {
34603
&hellip;
36010
…
34604
36011
virtual int bar();
34605
&hellip;
36012
…
34606
36013
};
34607
36014
</PRE>
34608
36015
</DIV>
35495
36902
<P><B> Python Dictionary Functions</B></P>
35496
36903
<DIV class="code">
35497
36904
<PRE>
35498
write me
36905
PyObject *PyDict_New();
36906
int PyDict_Check(PyObject *);
36907
int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val);
36908
int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val);
36909
int PyDict_DelItem(PyObject *p, PyObject *key);
36910
int PyDict_DelItemString(PyObject *p, char *key);
36911
PyObject* PyDict_Keys(PyObject *p);
36912
PyObject* PyDict_Values(PyObject *p);
36913
PyObject* PyDict_GetItem(PyObject *p, PyObject *key);
36914
PyObject* PyDict_GetItemString(PyObject *p, const char *key);
36915
int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue);
36916
Py_ssize_t PyDict_Size(PyObject *p);
36917
int PyDict_Update(PyObject *a, PyObject *b);
36918
int PyDict_Merge(PyObject *a, PyObject *b, int override);
36919
PyObject* PyDict_Items(PyObject *p);
35499
36920
</PRE>
35500
36921
</DIV>
35501
36922
<P><B> Python File Conversion Functions</B></P>
36107
37528
<LI><A href="#Ruby_nn21">C++ Operators</A></LI>
36108
37529
<LI><A href="#Ruby_nn22">C++ namespaces</A></LI>
36109
37530
<LI><A href="#Ruby_nn23">C++ templates</A></LI>
37531
<LI><A href="#Ruby_nn23_1">C++ Standard Template Library (STL)</A></LI>
37532
<LI><A href="#C_STL_Functors">C++ STL Functors</A></LI>
37533
<LI><A href="#Ruby_C_Iterators">C++ STL Iterators</A></LI>
36110
37534
<LI><A href="#Ruby_nn24">C++ Smart Pointers</A></LI>
36111
37535
<LI><A href="#Ruby_nn25">Cross-Language Polymorphism</A>
36112
37536
<UL>
36127
37551
<LI><A href="#Ruby_nn33">Exception handling</A>
36128
37552
<UL>
36129
37553
<LI><A href="#Ruby_nn34">Using the %exception directive</A></LI>
37554
<LI><A href="#Ruby_nn34_2">Handling Ruby Blocks</A></LI>
36130
37555
<LI><A href="#Ruby_nn35">Raising exceptions</A></LI>
36131
37556
<LI><A href="#Ruby_nn36">Exception classes</A></LI>
36132
37557
</UL>
36134
37559
<LI><A href="#Ruby_nn37">Typemaps</A>
36135
37560
<UL>
36136
37561
<LI><A href="#Ruby_nn38">What is a typemap?</A></LI>
36137
<LI><A href="#Ruby_nn39">Ruby typemaps</A></LI>
37562
<LI><A href="#Ruby_Typemap_scope">Typemap scope</A></LI>
37563
<LI><A href="#Ruby_Copying_a_typemap">Copying a typemap</A></LI>
37564
<LI><A href="#Ruby_Deleting_a_typemap">Deleting a typemap</A></LI>
37565
<LI><A href="#Ruby_Placement_of_typemaps">Placement of typemaps</A></LI>
37566
<LI><A href="#Ruby_nn39">Ruby typemaps</A>
37567
<UL>
37568
<LI><A href="#Ruby_in_typemap"> "in" typemap</A></LI>
37569
<LI><A href="#Ruby_typecheck_typemap">"typecheck" typemap</A></LI>
37570
<LI><A href="#Ruby_out_typemap"> "out" typemap</A></LI>
37571
<LI><A href="#Ruby_arginit_typemap">"arginit" typemap</A></LI>
37572
<LI><A href="#Ruby_default_typemap">"default" typemap</A></LI>
37573
<LI><A href="#Ruby_check_typemap">"check" typemap</A></LI>
37574
<LI><A href="#Ruby_argout_typemap_">"argout" typemap</A></LI>
37575
<LI><A href="#Ruby_freearg_typemap_">"freearg" typemap</A></LI>
37576
<LI><A href="#Ruby_newfree_typemap">"newfree" typemap</A></LI>
37577
<LI><A href="#Ruby_memberin_typemap">"memberin" typemap</A></LI>
37578
<LI><A href="#Ruby_varin_typemap">"varin" typemap</A></LI>
37579
<LI><A href="#Ruby_varout_typemap_">"varout" typemap</A></LI>
37580
<LI><A href="#Ruby_throws_typemap">"throws" typemap</A></LI>
37581
<LI><A href="#Ruby_directorin_typemap">directorin typemap</A></LI>
37582
<LI><A href="#Ruby_directorout_typemap">directorout typemap</A></LI>
37583
<LI><A href="#Ruby_directorargout_typemap">directorargout typemap</A></LI>
37584
<LI><A href="#Ruby_ret_typemap">ret typemap</A></LI>
37585
<LI><A href="#Ruby_globalin_typemap">globalin typemap</A></LI>
37586
</UL>
37587
</LI>
36138
37588
<LI><A href="#Ruby_nn40">Typemap variables</A></LI>
36139
37589
<LI><A href="#Ruby_nn41">Useful Functions</A>
36140
37590
<UL>
36156
37606
<LI><A href="#Ruby_nn52">Example: STL Vector to Ruby Array</A></LI>
36157
37607
</UL>
36158
37608
</LI>
37609
<LI><A href="#Ruby_nn65">Docstring Features</A>
37610
<UL>
37611
<LI><A href="#Ruby_nn66">Module docstring</A></LI>
37612
<LI><A href="#Ruby_nn67">%feature("autodoc")</A>
37613
<UL>
37614
<LI><A href="#Ruby_nn68">%feature("autodoc", "0")</A></LI>
37615
<LI><A href="#Ruby_autodoc1">%feature("autodoc", "1")</A></LI>
37616
<LI><A href="#Ruby_autodoc2">%feature("autodoc", "2")</A></LI>
37617
<LI><A href="#Ruby_feature_autodoc3">%feature("autodoc", "3")</A></LI>
37618
<LI><A href="#Ruby_nn70">%feature("autodoc", "docstring")</A></LI>
37619
</UL>
37620
</LI>
37621
<LI><A href="#Ruby_nn71">%feature("docstring")</A></LI>
37622
</UL>
37623
</LI>
36159
37624
<LI><A href="#Ruby_nn53">Advanced Topics</A>
36160
37625
<UL>
36161
37626
<LI><A href="#Ruby_nn54">Operator overloading</A></LI>
36170
37635
<LI><A href="#Ruby_nn60">Object Tracking</A></LI>
36171
37636
<LI><A href="#Ruby_nn61">Mark Functions</A></LI>
36172
37637
<LI><A href="#Ruby_nn62">Free Functions</A></LI>
37638
<LI><A href="#Ruby_nn63">Embedded Ruby and the C++ Stack</A></LI>
36173
37639
</UL>
36174
37640
</LI>
36175
37641
</UL>
36188
37654
the reader has a basic understanding of Ruby.</P>
36189
37655
<H3><A name="Ruby_nn3"></A>30.1.1 Running SWIG</H3>
36190
37656
<P> To build a Ruby module, run SWIG using the <TT>-ruby</TT> option:</P>
36191
<DIV class="code">
37657
<DIV class="code shell">
36192
37658
<PRE>$ <B>swig -ruby example.i</B>
36193
37659
</PRE>
36194
37660
</DIV>
36195
37661
<P> If building a C++ extension, add the <TT>-c++</TT> option:</P>
36196
<DIV class="code">
37662
<DIV class="code shell">
36197
37663
<PRE>$ <B>swig -c++ -ruby example.i</B>
36198
37664
</PRE>
36199
37665
</DIV>
36205
37671
<P> In order to compile the wrapper code, the compiler needs the <TT>
36206
37672
ruby.h</TT> header file. This file is usually contained in a directory
36207
37673
such as</P>
36208
<DIV class="code">
36209
<PRE>/usr/local/lib/ruby/1.6/i686-linux/ruby.h
37674
<DIV class="code shell diagram">
37675
<PRE>/usr/lib/ruby/1.8/x86_64-linux-gnu/ruby.h
37676
<BR>/usr/local/lib/ruby/1.6/i686-linux/ruby.h
36210
37677
<BR></PRE>
36211
37678
</DIV>
36212
37679
<P> The exact location may vary on your machine, but the above location
36213
37680
is typical. If you are not entirely sure where Ruby is installed, you
36214
37681
can run Ruby to find out. For example:</P>
36215
<DIV class="code">
36216
<PRE>
36217
$ <B>ruby -e 'puts $:.join("\n")'</B>
37682
<DIV class="code shell">
37683
<PRE>$ <B>ruby -e 'puts $:.join("\n")'</B>
36218
37684
<BR>/usr/local/lib/ruby/site_ruby/1.6 /usr/local/lib/ruby/site_ruby/1.6/i686-linux
36219
/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .
36220
</PRE>
37685
<BR>/usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/1.6 /usr/local/lib/ruby/1.6/i686-linux .
37686
<BR> </PRE>
36221
37687
</DIV>
36222
37688
<H3><A name="Ruby_nn5"></A>30.1.3 Compiling a dynamic module</H3>
36223
37689
<P> Ruby extension modules are typically compiled into shared libraries
36229
37695
<LI>
36230
37696
<P>Create a file called <TT>extconf.rb</TT> that looks like the
36231
37697
following:</P>
36232
<DIV class="code">
37698
<DIV class="code targetlang">
36233
37699
<PRE>require 'mkmf'
36234
37700
<BR>create_makefile('example')
36235
37701
<BR></PRE>
36236
37702
</DIV></LI>
36237
37703
<LI>
36238
37704
<P>Type the following to build the extension:</P>
36239
<DIV class="code">
37705
<DIV class="code shell">
36240
37706
<PRE>$ <B>ruby extconf.rb</B>
36241
37707
<BR>$ <B>make</B>
36242
37708
<BR>$ <B>make install</B>
36246
37712
<P> Of course, there is the problem that mkmf does not work correctly on
36247
37713
all platforms, e.g, HPUX. If you need to add your own make rules to the
36248
37714
file that <TT>extconf.rb</TT> produces, you can add this:</P>
36249
<DIV class="code">
37715
<DIV class="code targetlang">
36250
37716
<PRE>open("Makefile", "a") { |mf|
36251
37717
<BR> puts <<EOM
36252
37718
<BR> # Your make rules go here
36259
37725
correct compiler and linker flags for your build platform. For example,
36260
37726
a typical sequence of commands for the Linux operating system would
36261
37727
look something like this:</P>
36262
<DIV class="code">
37728
<DIV class="code shell">
36263
37729
<PRE>$ <B>swig -ruby example.i</B>
36264
37730
<BR>$ <B>gcc -c example.c</B>
36265
37731
<BR>$ <B>gcc -c example_wrap.c -I/usr/local/lib/ruby/1.6/i686-linux</B>
36271
37737
consult the manual pages for your compiler and linker to determine the
36272
37738
correct set of options. You might also check the <A href="http://www.dabeaz.com/cgi-bin/wiki.pl">
36273
37739
SWIG Wiki</A> for additional information.</P>
36274
<P> <A name="n6"></A></P>
36275
37740
<H3><A name="Ruby_nn6"></A>30.1.4 Using your module</H3>
36276
37741
<P> Ruby<I> module</I> names must be capitalized, but the convention for
36277
37742
Ruby<I> feature</I> names is to use lowercase names. So, for example,
36278
37743
the<B> Etc</B> extension module is imported by requiring the<B> etc</B>
36279
37744
feature:</P>
36280
<DIV class="code">
37745
<DIV class="code targetlang">
36281
37746
<PRE># The feature name begins with a lowercase letter...
36282
37747
<BR>require 'etc'
36283
37748
<BR>
36306
37771
the Ruby source, adding an entry to the <TT>ext/Setup</TT> file, adding
36307
37772
your directory to the list of extensions in the file, and finally
36308
37773
rebuilding Ruby.</P>
36309
<P><A name="n8"></A></P>
36310
37774
<H3><A name="Ruby_nn8"></A>30.1.6 Compilation of C++ extensions</H3>
36311
37775
<P> On most machines, C++ extension modules should be linked using the
36312
37776
C++ compiler. For example:</P>
36313
<DIV class="code">
37777
<DIV class="code shell">
36314
37778
<PRE>$ <B>swig -c++ -ruby example.i</B>
36315
37779
<BR>$ <B>g++ -c example.cxx</B>
36316
37780
<BR>$ <B>g++ -c example_wrap.cxx -I/usr/local/lib/ruby/1.6/i686-linux</B>
36326
37790
use the <TT>mkmf</TT> module's <TT>append_library()</TT> method to add
36327
37791
one of the C++ runtime libraries to the list of libraries linked into
36328
37792
your extension, e.g.</P>
36329
<DIV class="code">
37793
<DIV class="code targetlang">
36330
37794
<PRE>require 'mkmf'
36331
37795
<BR>$libs = append_library($libs, "supc++")
36332
37796
<BR>create_makefile('example')
36340
37804
recent versions of Ruby, the procedure described above (i.e. using an <TT>
36341
37805
extconf.rb</TT> script) will work with Windows as well; you should be
36342
37806
able to build your code into a DLL by typing:</P>
36343
<DIV class="code">
37807
<DIV class="code shell">
36344
37808
<PRE>C:\swigtest> <B>ruby extconf.rb</B>
36345
37809
<BR>C:\swigtest> <B>nmake</B>
36346
37810
<BR>C:\swigtest> <B>nmake install</B>
36352
37816
order to build extensions, you may need to download the source
36353
37817
distribution to the Ruby package, as you will need the Ruby header
36354
37818
files.</P>
36355
<P><A name="n10"></A></P>
36356
37819
<H3><A name="Ruby_nn10"></A>30.2.1 Running SWIG from Developer Studio</H3>
36357
37820
<P> If you are developing your application within Microsoft developer
36358
37821
studio, SWIG can be invoked as a custom build option. The process
36394
37857
the wrapper file. To run your new Ruby extension, simply run Ruby and
36395
37858
use the <TT>require</TT> command as normal. For example if you have
36396
37859
this ruby file run.rb:</P>
36397
<DIV class="code">
37860
<DIV class="code targetlang">
36398
37861
<PRE># file: run.rb
36399
37862
<BR>require 'Example'
36400
37863
<BR>
36404
37867
</DIV>
36405
37868
<P> Ensure the dll just built is in your path or current directory, then
36406
37869
run the Ruby script from the DOS/Command prompt:</P>
36407
<DIV class="code">
37870
<DIV class="code shell">
36408
37871
<PRE>C:\swigtest> <B>ruby run.rb</B>
36409
37872
<BR>Foo = 3.0
36410
37873
<BR></PRE>
36450
37913
<!--span style="font-family: monospace;"-->
36451
37914
-prefix command line option:
36452
37915
<BR></P>
36453
<DIV class="code">
37916
<DIV class="code shell">
36454
37917
<PRE>$ <B>swig -ruby -prefix "foo::bar::" example.i</B></PRE>
36455
37918
</DIV>
36456
37919
<P> Starting with SWIG 1.3.20, you can also choose to wrap everything
36457
37920
into the global module by specifying the <TT>-globalmodule</TT> option
36458
37921
on the SWIG command line, i.e.</P>
36459
<DIV class="code">
37922
<DIV class="code shell">
36460
37923
<PRE>$ <B>swig -ruby -globalmodule example.i</B></PRE>
36461
37924
</DIV>
36462
37925
<P> Note that this does not relieve you of the requirement of specifying
36488
37951
</DIV>
36489
37952
<P> SWIG will generate a method<I> fact</I> in the<I> Example</I> module
36490
37953
that can be used like so:</P>
36491
<DIV class="code">
37954
<DIV class="code targetlang">
36492
37955
<PRE>$ <B>irb</B>
36493
37956
<BR>irb(main):001:0> <B>require 'example'</B>
36494
37957
<BR>true
36513
37976
<BR></PRE>
36514
37977
</DIV>
36515
37978
<P> Now look at the Ruby interface:</P>
36516
<DIV class="code">
37979
<DIV class="code targetlang">
36517
37980
<PRE>$ <B>irb</B>
36518
37981
<BR>irb(main):001:0> <B>require 'Example'</B>
36519
37982
<BR>true
36527
37990
</DIV>
36528
37991
<P> If you make an error in variable assignment, you will receive an
36529
37992
error message. For example:</P>
36530
<DIV class="code">
37993
<DIV class="code targetlang">
36531
37994
<PRE>irb(main):005:0> <B>Example.Variable2 = "hello"</B>
36532
37995
<BR>TypeError: no implicit conversion to float from string
36533
37996
<BR>from (irb):5:in `Variable2='
36565
38028
</DIV>
36566
38029
<P> Remember to use the :: operator in Ruby to get at these constant
36567
38030
values, e.g.</P>
36568
<DIV class="code">
38031
<DIV class="code targetlang">
36569
38032
<PRE>$ <B>irb</B>
36570
38033
<BR>irb(main):001:0> <B>require 'Example'</B>
36571
38034
<BR>true
36585
38048
</DIV>
36586
38049
<P> For this case, the<I> get_foo()</I> method returns an instance of an
36587
38050
internally generated Ruby class:</P>
36588
<DIV class="code">
38051
<DIV class="code targetlang">
36589
38052
<PRE>irb(main):001:0> <B>foo = Example::get_foo()</B>
36590
38053
<BR>#<SWIG::TYPE_p_Foo:0x402b1654>
36591
38054
<BR></PRE>
36603
38066
<BR></PRE>
36604
38067
</DIV>
36605
38068
<P> gets wrapped as a <TT>Vector</TT> class, with Ruby instance methods <TT>
36606
x</TT>, <TT> x=</TT>, <TT>y</TT> and <TT>y=</TT>. These methods can be
38069
x</TT>, <TT>x=</TT>, <TT>y</TT> and <TT>y=</TT>. These methods can be
36607
38070
used to access structure data from Ruby as follows:</P>
36608
<DIV class="code">
38071
<DIV class="code targetlang">
36609
38072
<PRE>$ <B>irb</B>
36610
38073
<BR>irb(main):001:0> <B>require 'Example'</B>
36611
38074
<BR>true
36711
38174
<LI> a<I> print</I> singleton method for the class.</LI>
36712
38175
</UL>
36713
38176
<P> In Ruby, these functions are used as follows:</P>
36714
<DIV class="code">
38177
<DIV class="code targetlang">
36715
38178
<PRE>require 'Example'
36716
38179
<BR>
36717
38180
<BR>l = Example::List.new
36788
38251
as an "ancestor" of <TT>Derived</TT> (i.e. the<EM> is_a?</EM>
36789
38252
relationship would fail). When SWIG processes this interface file,
36790
38253
you'll see a warning message like:</P>
36791
<DIV class="code">
38254
<DIV class="code shell">
36792
38255
<PRE>example.i:5: Warning(802): Warning for Derived: Base Base2 ignored.
36793
38256
<BR>Multiple inheritance is not supported in Ruby.
36794
38257
<BR></PRE>
36798
38261
multiple inheritance introduces some limitations, this is an optional
36799
38262
feature that you can activate with the <TT>-minherit</TT> command-line
36800
38263
option:</P>
36801
<DIV class="code">
38264
<DIV class="code shell">
36802
38265
<PRE>$ <B>swig -c++ -ruby -minherit example.i</B></PRE>
36803
38266
</DIV>
36804
38267
<P> Using our previous example, if your SWIG interface file contains a
36818
38281
superclass. Each of these classes defines a nested module named <TT>
36819
38282
Impl</TT>, and it's in these nested <TT>Impl</TT> modules that the
36820
38283
actual instance methods for the classes are defined, i.e.</P>
36821
<DIV class="code">
38284
<DIV class="code targetlang">
36822
38285
<PRE>class Base1
36823
38286
<BR> module Impl
36824
38287
<BR> # Define Base1 methods here
36850
38313
<P>The primary drawback is that, unlike the default mode of operation,
36851
38314
neither <TT>Base1</TT> nor <TT>Base2</TT> is a true superclass of <TT>
36852
38315
Derived</TT> anymore:</P>
36853
<DIV class="code">
38316
<DIV class="code targetlang">
36854
38317
<PRE>obj = Derived.new
36855
38318
<BR>obj.is_a? Base1 # this will return false...
36856
38319
<BR>obj.is_a? Base2 # ... and so will this
36869
38332
<BR></PRE>
36870
38333
</DIV>
36871
38334
<P> You can use them in Ruby in a straightforward manner:</P>
36872
<DIV class="code">
38335
<DIV class="code targetlang">
36873
38336
<PRE>irb(main):001:0> <B>foo(3)</B> # foo(int)
36874
38337
<BR>irb(main):002:0> <B>foo("Hello")</B> # foo(char *c)
36875
38338
<BR></PRE>
36885
38348
<BR></PRE>
36886
38349
</DIV>
36887
38350
<P>you can write Ruby code like this:</P>
36888
<DIV class="code">
38351
<DIV class="code targetlang">
36889
38352
<PRE>irb(main):001:0> <B>f = Foo.new</B> # Create a Foo
36890
38353
<BR>irb(main):002:0> <B>g = Foo.new(f)</B> # Copy f
36891
38354
<BR></PRE>
36905
38368
</DIV>
36906
38369
<P> If declarations such as these appear, you will get a warning message
36907
38370
like this:</P>
36908
<DIV class="code">
38371
<DIV class="code shell">
36909
38372
<PRE>example.i:12: Warning(509): Overloaded spam(short) is shadowed by spam(int)
36910
38373
<BR>at example.i:11.
36911
38374
<BR> </PRE>
36933
38396
the input does not matter except in situations where ambiguity
36934
38397
arises--in this case, the first declaration takes precedence.</P>
36935
38398
<P>Please refer to the <A href="#SWIGPlus">"SWIG and C++"</A> chapter
36936
for more information about overloading. <A name="n21"></A></P>
38399
for more information about overloading.</P>
36937
38400
<H3><A name="Ruby_nn21"></A>30.3.10 C++ Operators</H3>
36938
38401
<P> For the most part, overloaded operators are handled automatically by
36939
38402
SWIG and do not require any special treatment on your part. So if your
36959
38422
<BR></PRE>
36960
38423
</DIV>
36961
38424
<P>Now, in Ruby, you can do this:</P>
36962
<DIV class="code">
38425
<DIV class="code targetlang">
36963
38426
<PRE>a = Example::Complex.new(2, 3)
36964
38427
<BR>b = Example::Complex.new(4, -1)
36965
38428
<BR>c = Example.add_complex(a, b)
36984
38447
<BR></PRE>
36985
38448
</DIV>
36986
38449
<P>it works in Ruby as follows:</P>
36987
<DIV class="code">
38450
<DIV class="code targetlang">
36988
38451
<PRE>irb(main):001:0> <B>require 'example'</B>
36989
38452
<BR>true
36990
38453
<BR>irb(main):002:0> <B>Example.fact(3)</B>
37044
38507
<BR></PRE>
37045
38508
</DIV>
37046
38509
<P>In Ruby:</P>
37047
<DIV class="code">
38510
<DIV class="code targetlang">
37048
38511
<PRE>irb(main):001:0> <B>require 'example'</B>
37049
38512
<BR>true
37050
38513
<BR>irb(main):002:0> <B>p = Example::Pairii.new(3, 4)</B>
37055
38518
<BR>4
37056
38519
<BR></PRE>
37057
38520
</DIV>
38521
<H3><A name="Ruby_nn23_1"></A>30.3.13 C++ Standard Template Library
38522
(STL)</H3>
37058
38523
<P> On a related note, the standard SWIG library contains a number of
37059
38524
modules that provide typemaps for standard C++ library classes (such as
37060
38525
<TT>std::pair</TT>, <TT>std::string</TT> and <TT>std::vector</TT>).
37081
38546
<BR>float sum(const std::vector<float>& values);
37082
38547
<BR></PRE>
37083
38548
</DIV>
37084
<P> Obviously, there is a lot more to template wrapping than shown in
38549
<P>Ruby's STL wrappings provide additional methods to make them behave
38550
more similarly to Ruby's native classes.</P>
38551
<P>Thus, you can do, for example:</P>
38552
<DIV class="targetlang">
38553
<PRE>v = IntVector.new
38554
<!--span class="targetlang"-->
38555
<BR>v << 2
38556
<!--span class="targetlang"-->
38557
<BR>v << 3
38558
<BR>v << 4
38559
<BR>v.each { |x| puts x }
38560
<BR>
38561
<!--span style="font-weight: bold;"-->
38562
<BR>=> 2
38563
<BR style="font-weight: bold;">
38564
<!--span style="font-weight: bold;"-->
38565
3
38566
<BR style="font-weight: bold;">
38567
<!--span style="font-weight: bold;"-->
38568
4
38569
<BR>v.delete_if { |x| x == 3 }
38570
<BR>
38571
<!--span style="font-weight: bold;"-->
38572
=> [2,4]</PRE>
38573
</DIV>
38574
<P>The SWIG Ruby module provides also the ability for all the STL
38575
containers to carry around Ruby native objects (Fixnum, Classes, etc)
38576
making them act almost like Ruby's own Array, Hash, etc. To do that,
38577
you need to define a container that contains a swig::GC_VALUE, like:</P>
38578
<DIV class="code" style="font-family: monospace;">%module nativevector
38579
<BR>
38580
<BR> %{
38581
<BR> std::vector< swig::GC_VALUE > NativeVector;
38582
<BR> %}
38583
<BR>
38584
<BR> %template(NativeVector) std::vector< swig::GC_VALUE >;
38585
<BR></DIV>
38586
<BR>
38587
<P>This vector can then contain any Ruby object, making them almost
38588
identical to Ruby's own Array class.</P>
38589
<DIV class="targetlang">
38590
<!--span style="font-family: monospace;"-->
38591
require 'nativevector'
38592
<BR style="font-family: monospace;">
38593
<!--span style="font-family: monospace;"-->
38594
include NativeVector
38595
<BR style="font-family: monospace;">
38596
<BR style="font-family: monospace;">
38597
<!--span style="font-family: monospace;"-->
38598
v = NativeVector.new
38599
<BR style="font-family: monospace;">
38600
<!--span style="font-family: monospace;"-->
38601
v << 1
38602
<BR style="font-family: monospace;">
38603
<!--span style="font-family: monospace;"-->
38604
v << [1,2]
38605
<BR style="font-family: monospace;">
38606
<!--span style="font-family: monospace;"-->
38607
v << 'hello'
38608
<BR style="font-family: monospace;">
38609
<BR style="font-family: monospace;">
38610
<!--span style="font-family: monospace;"-->
38611
class A; end
38612
<BR style="font-family: monospace;">
38613
<BR style="font-family: monospace;">
38614
<!--span style="font-family: monospace;"-->
38615
v << A.new
38616
<BR style="font-family: monospace;">
38617
<BR style="font-family: monospace;">
38618
<!--span style="font-family: monospace;"-->
38619
puts v
38620
<BR style="font-family: monospace;">
38621
<!--span style="font-weight: bold; font-family: monospace;"-->
38622
=> [1, [1,2], 'hello', #<A:0x245325>]</DIV>
38623
<BR>
38624
<P>Obviously, there is a lot more to template wrapping than shown in
37085
38625
these examples. More details can be found in the <A href="#SWIGPlus">
37086
38626
SWIG and C++</A> chapter.</P>
37087
<H3><A name="Ruby_nn24"></A>30.3.13 C++ Smart Pointers</H3>
38627
<H3><A name="C_STL_Functors"></A>30.3.14 C++ STL Functors</H3>
38628
<P>Some containers in the STL allow you to modify their default behavior
38629
by using so called functors or function objects. Functors are often
38630
just a very simple struct with
38631
<!--span style="font-family: monospace;"-->
38632
operator() redefined or an actual C/C++ function. This allows you, for
38633
example, to always keep the sort order of a STL container to your
38634
liking.</P>
38635
<P>The Ruby STL mappings allows you to modify those containers that
38636
support functors using Ruby procs or methods, instead. Currently, this
38637
includes
38638
<!--span style="font-family: monospace;"-->
38639
std::set,
38640
<!--span style="font-family: monospace;"-->
38641
set::map,
38642
<!--span style="font-family: monospace;"-->
38643
std::multiset and
38644
<!--span style="font-family: monospace;"-->
38645
std::multimap.</P>
38646
<P>The functors in swig are called
38647
<!--span style="font-family: monospace;"-->
38648
swig::UnaryFunction and
38649
<!--span style="font-family: monospace;"-->
38650
swig::BinaryFunction.
38651
<BR> For C++ predicates (ie. functors that must return bool as a result)
38652
<!--span style="font-family: monospace;"-->
38653
swig::UnaryPredicate and
38654
<!--span style="font-family: monospace;"-->
38655
swig::BinaryPredicate are provided.</P>
38656
<P>As an example, if given this swig file:</P>
38657
<DIV class="code" style="font-family: monospace;">%module intset;
38658
<BR>
38659
<BR> %include std_set.i
38660
<BR>
38661
<BR> %typemap(IntSet) std::set< int, swig::BinaryPredicate >;</DIV>
38662
<P>You can then use the set from Ruby with or without a proc object as a
38663
predicate:</P>
38664
<DIV class="targetlang" style="font-family: monospace;">require 'intset'
38665
<BR> include Intset
38666
<BR>
38667
<BR> # Default sorting behavior defined in C++
38668
<BR> a = IntSet.new
38669
<BR> a << 1
38670
<BR> a << 2
38671
<BR> a << 3
38672
<BR> a
38673
<BR>
38674
<!--span style="font-weight: bold;"-->
38675
=> [1,2,3]
38676
<BR>
38677
<BR> # Custom sorting behavior defined by a Ruby proc<DIV>
38678
<!--span class="targetlang"-->
38679
b = IntSet.new( proc { |a,b| a > b } )
38680
<BR> b << 1
38681
<BR> b << 2
38682
<BR> b << 3
38683
<BR> b
38684
<BR style="font-weight: bold;">
38685
<!--span style="font-weight: bold;"-->
38686
=> [3,2,1]</DIV></DIV>
38687
<H3><A name="Ruby_C_Iterators"></A>30.3.15 C++ STL Iterators</H3>
38688
<P>The STL is well known for the use of iterators. There are a number
38689
of iterators possible with different properties, but in general there
38690
are two main categories: const iterators and non-const iterators. The
38691
const iterators can access and not modify the values they point at,
38692
while the non-const iterators can both read and modify the values.</P>
38693
<P>The Ruby STL wrappings support both type of iterators by using a
38694
proxy class in-between. This proxy class is
38695
<!--span style="font-family: monospace;"-->
38696
swig::Iterator or swig::ConstIterator. Derived from them are template
38697
classes that need to be initialized with the actual iterator for the
38698
container you are wrapping and often times with the beginning and
38699
ending points of the iteration range. </P>
38700
<P>The SWIG STL library already provides typemaps to all the standard
38701
containers to do this wrapping automatically for you, but if you have
38702
your own STL-like iterator, you will need to write your own typemap for
38703
them. For out typemaps, the special functions
38704
<!--span style="font-family: monospace;"-->
38705
make_const_iterator and
38706
<!--span style="font-family: monospace;"-->
38707
make_nonconst_iterator are provided.</P>
38708
<P>These can be used either like:</P>
38709
<DIV class="code" style="font-family: monospace;">make_const_iterator(
38710
iterator, rubyclass );
38711
<BR> make_const_iterator( iterator, iterator_begin, iterator_end,
38712
rubyclass );</DIV>
38713
<P>The iterators support a
38714
<!--span style="font-family: monospace;"-->
38715
next() and
38716
<!--span style="font-family: monospace;"-->
38717
previous() member function to just change the iterator without
38718
returning anything.
38719
<!--span style="font-family: monospace;"-->
38720
previous() should obviously only be used for bidirectional iterators.
38721
You can also advance the iterator multiple steps by using standard
38722
math operations like
38723
<!--span style="font-family: monospace;"-->
38724
+=.</P>
38725
<P>The value the iterator points at can be accessed with
38726
<!--span style="font-family: monospace;"-->
38727
value() -- this is equivalent to dereferencing it with
38728
<!--span style="font-family: monospace;"-->
38729
*i. For non-const iterators, a
38730
<!--span style="font-family: monospace;"-->
38731
value=() function is also provided which allows you to change the value
38732
pointed by the iterator. This is equivalent to the C++ construct of
38733
dereferencing and assignment, like
38734
<!--span style="font-family: monospace;"-->
38735
*i = something. </P>
38736
<P>Thus, given say a vector class of doubles defined as:</P>
38737
<DIV class="code" style="font-family: monospace;">
38738
<!--span class="code"-->
38739
%module doublevector
38740
<BR class="code">
38741
<!--span class="code"-->
38742
<BR> %include std_vector.i
38743
<BR class="code">
38744
<!--span class="code"-->
38745
<BR> %template(DoubleVector) std::vector<double>;</DIV>
38746
<P>Its iterator can then be used from Ruby like:</P>
38747
<DIV class="targetlang" style="font-family: monospace;">require
38748
'doublevector'
38749
<BR> include Doublevector
38750
<BR>
38751
<BR> v = DoubleVector.new
38752
<BR> v << 1
38753
<BR> v << 2
38754
<BR> v << 3
38755
<BR>
38756
<BR> #
38757
<BR> # an elaborate and less efficient way of doing v.map! { |x| x+2 }
38758
<BR> #
38759
<BR> i = v.begin
38760
<BR> e = v.end
38761
<BR> while i != e
38762
<BR> val = i.value
38763
<BR> val += 2
38764
<BR> i.value = val
38765
<BR> i.next
38766
<BR> end
38767
<BR> i
38768
<BR>
38769
<!--span style="font-weight: bold;"-->
38770
>> [3, 4, 5 ]</DIV>
38771
<BR>
38772
<P>If you'd rather have STL classes without any iterators, you should
38773
define
38774
<!--span style="font-family: monospace;"-->
38775
-DSWIG_NO_EXPORT_ITERATOR_METHODS when running swig.</P>
38776
<H3><A name="Ruby_nn24"></A>30.3.16 C++ Smart Pointers</H3>
37088
38777
<P> In certain C++ programs, it is common to use classes that have been
37089
38778
wrapped by so-called "smart pointers." Generally, this involves the use
37090
38779
of a template class that implements <TT>operator->()</TT> like this:</P>
37124
38813
<BR></PRE>
37125
38814
</DIV>
37126
38815
<P>Now, in Ruby, everything should just "work":</P>
37127
<DIV class="code">
38816
<DIV class="code targetlang">
37128
38817
<PRE>irb(main):001:0> <B>p = Example::CreateFoo()</B> # Create a smart-pointer somehow
37129
38818
<BR>#<Example::SmartPtrFoo:0x4016f4df>
37130
38819
<BR>irb(main):002:0> <B>p.x = 3</B> # Foo::x
37135
38824
<P> If you ever need to access the underlying pointer returned by <TT>
37136
38825
operator->()</TT> itself, simply use the <TT>__deref__()</TT> method.
37137
38826
For example:</P>
37138
<DIV class="code">
38827
<DIV class="code targetlang">
37139
38828
<PRE>irb(main):004:0> <B>f = p.__deref__()</B> # Returns underlying Foo *
37140
38829
<BR></PRE>
37141
38830
</DIV>
37142
<H3><A name="Ruby_nn25"></A>30.3.14 Cross-Language Polymorphism</H3>
38831
<H3><A name="Ruby_nn25"></A>30.3.17 Cross-Language Polymorphism</H3>
37143
38832
<P> SWIG's Ruby module supports cross-language polymorphism (a.k.a. the
37144
38833
"directors" feature) similar to that for SWIG's Python module. Rather
37145
than duplicate the information presented in the <A href="#Python">
37146
Python</A> chapter, this section just notes the differences that you
37147
need to be aware of when using this feature with Ruby.</P>
37148
<H4><A name="Ruby_nn26"></A>30.3.14.1 Exception Unrolling</H4>
38834
than duplicate the information presented in the <A href="Ruby">Python</A>
38835
chapter, this section just notes the differences that you need to be
38836
aware of when using this feature with Ruby.</P>
38837
<H4><A name="Ruby_nn26"></A>30.3.17.1 Exception Unrolling</H4>
37149
38838
<P> Whenever a C++ director class routes one of its virtual member
37150
38839
function calls to a Ruby instance method, there's always the
37151
38840
possibility that an exception will be raised in the Ruby code. By
37182
38871
When this parameter is specified, SWIG will automatically change
37183
38872
constant, class and method names to conform with the standard Ruby
37184
38873
naming conventions. For example:</P>
37185
<DIV class="code">
38874
<DIV class="code shell">
37186
38875
<PRE>$ <B>swig -ruby -autorename example.i</B>
37187
38876
</PRE>
37188
38877
</DIV>
37214
38903
<BR> return $self->length();
37215
38904
<BR> }
37216
38905
<BR>}
37217
</PRE>
38906
<BR> </PRE>
37218
38907
</DIV>
37219
38908
<P> A better solution is to use the <TT>%alias</TT> directive (unique to
37220
38909
SWIG's Ruby module). The previous example could then be rewritten as:</P>
37231
38920
<BR> size_t length() const;
37232
38921
<BR>};
37233
38922
<BR>
37234
</PRE>
38923
<BR></PRE>
37235
38924
</DIV>
37236
38925
<P> Multiple aliases can be associated with a method by providing a
37237
38926
comma-separated list of aliases to the <TT>%alias</TT> directive, e.g.</P>
37269
38958
<BR>
37270
38959
<BR>int is_it_safe();
37271
38960
<BR>
37272
</PRE>
38961
<BR></PRE>
37273
38962
</DIV>
37274
38963
<P> A better solution is to use the <TT>%predicate</TT> directive
37275
38964
(unique to SWIG's Ruby module) to designate a method as a predicate
37279
38968
<BR>
37280
38969
<BR>int is_it_safe();
37281
38970
<BR>
37282
</PRE>
38971
<BR></PRE>
37283
38972
</DIV>
37284
38973
<P>This method would be invoked from Ruby code like this:</P>
37285
<DIV class="code">
38974
<DIV class="code targetlang">
37286
38975
<PRE>irb(main):001:0> <B>Example::is_it_safe?</B>
37287
38976
<BR>true
37288
38977
<BR>
37289
</PRE>
38978
<BR></PRE>
37290
38979
</DIV>
37291
38980
<P> The <TT>%predicate</TT> directive is implemented using SWIG's
37292
38981
"features" mechanism and so the same name matching rules used for other
37306
38995
<DIV class="code">
37307
38996
<PRE>%bang sort!(arr);
37308
38997
<BR>
37309
<BR>int sort(int arr[]); </PRE>
38998
<BR>int sort(int arr[]); </PRE>
37310
38999
</DIV>
37311
39000
<P>This method would be invoked from Ruby code like this:</P>
37312
39001
<DIV class="code">
37321
39010
setter methods. For example:</P>
37322
39011
<DIV class="code">
37323
39012
<PRE>class Foo {
37324
Foo() {}
37325
37326
int getValue() { return value_; }
37327
37328
void setValue(int value) { value_ = value; }
37329
37330
private:
37331
int value_;
37332
};</PRE>
39013
<BR> Foo() {}
39014
<BR>
39015
<BR> int getValue() { return value_; }
39016
<BR>
39017
<BR> void setValue(int value) { value_ = value; }
39018
<BR>
39019
<BR>private:
39020
<BR> int value_;
39021
<BR>};</PRE>
37333
39022
</DIV>
37334
39023
<P>By default, SWIG will expose these methods to Ruby as <TT>get_value</TT>
37335
39024
and <TT>set_value.</TT> However, it more natural for these methods to
37337
39026
the methods to be used like this:</P>
37338
39027
<DIV class="code">
37339
39028
<PRE>irb(main):001:0> <B>foo = Foo.new()</B>
37340
irb(main):002:0> <B>foo.value = 5</B>
37341
irb(main):003:0> <B>puts foo.value</B></PRE>
39029
<BR>irb(main):002:0> <B>foo.value = 5</B>
39030
<BR>irb(main):003:0> <B>puts foo.value</B></PRE>
37342
39031
</DIV>
37343
39032
<P> This can be done by using the %rename directive:</P>
37344
39033
<DIV class="code">
37345
39034
<PRE>%rename("value") Foo::getValue();
37346
%rename("value=") Foo::setValue(int value);
37347
</PRE>
39035
<BR>%rename("value=") Foo::setValue(int value);
39036
<BR></PRE>
37348
39037
</DIV>
37349
39038
<P> </P>
37350
39039
<H2><A name="Ruby_nn32"></A>30.5 Input and output parameters</H2>
37371
39060
<BR></PRE>
37372
39061
</DIV>
37373
39062
<P>In Ruby, this allows you to pass simple values. For example:</P>
37374
<DIV class="code">
39063
<DIV class="code targetlang">
37375
39064
<PRE>a = Example.add(3,4)
37376
39065
<BR>puts a
37377
39066
<BR>7
37411
39100
<BR></PRE>
37412
39101
</DIV>
37413
39102
<P>In Ruby, a mutated parameter shows up as a return value. For example:</P>
37414
<DIV class="code">
39103
<DIV class="code targetlang">
37415
39104
<PRE>a = Example.negate(3)
37416
39105
<BR>print a
37417
39106
<BR>-3
37437
39126
</DIV>
37438
39127
<P> When used in Ruby, the function will return an array of multiple
37439
39128
values.</P>
37440
<DIV class="code">
39129
<DIV class="code targetlang">
37441
39130
<PRE>bytes, success, error_code = send_message("Hello World")
37442
39131
<BR>if not success
37443
39132
<BR> print "error #{error_code} : in send_message"
37459
39148
<BR></PRE>
37460
39149
</DIV>
37461
39150
<P>In Ruby:</P>
37462
<DIV class="code">
39151
<DIV class="code targetlang">
37463
39152
<PRE>r, c = Example.get_dimensions(m)
37464
39153
<BR></PRE>
37465
39154
</DIV>
37473
39162
<DIV class="code">
37474
39163
<PRE>class DoubleArray {
37475
39164
<BR> private:
37476
<BR> int n;
37477
<BR> double *ptr;
39165
<BR> int n;
39166
<BR> double *ptr;
37478
39167
<BR> public:
37479
<BR> // Create a new array of fixed size
37480
<BR> DoubleArray(int size) {
37481
<BR> ptr = new double[size];
37482
<BR> n = size;
37483
<BR> }
37484
<BR> // Destroy an array
37485
<BR> ~DoubleArray() {
37486
<BR> delete ptr;
37487
<BR> }
37488
<BR> // Return the length of the array
37489
<BR> int length() {
37490
<BR> return n;
37491
<BR> }
37492
<BR>
37493
<BR> // Get an array item and perform bounds checking.
37494
<BR> double getitem(int i) {
37495
<BR> if ((i >= 0) && (i < n))
37496
<BR> return ptr[i];
37497
<BR> else
37498
<BR> throw RangeError();
37499
<BR> }
37500
<BR> // Set an array item and perform bounds checking.
37501
<BR> void setitem(int i, double val) {
37502
<BR> if ((i >= 0) && (i < n))
37503
<BR> ptr[i] = val;
37504
<BR> else {
37505
<BR> throw RangeError();
37506
<BR> }
37507
<BR> }
39168
<BR> // Create a new array of fixed size
39169
<BR> DoubleArray(int size) {
39170
<BR> ptr = new double[size];
39171
<BR> n = size;
39172
<BR> }
39173
<BR>
39174
<BR> // Destroy an array
39175
<BR> ~DoubleArray() {
39176
<BR> delete ptr;
39177
<BR> }
39178
<BR>
39179
<BR> // Return the length of the array
39180
<BR> int length() {
39181
<BR> return n;
39182
<BR> }
39183
<BR>
39184
<BR> // Get an array item and perform bounds checking.
39185
<BR> double getitem(int i) {
39186
<BR> if ((i >= 0) && (i < n))
39187
<BR> return ptr[i];
39188
<BR> else
39189
<BR> throw RangeError();
39190
<BR> }
39191
<BR>
39192
<BR> // Set an array item and perform bounds checking.
39193
<BR> void setitem(int i, double val) {
39194
<BR> if ((i >= 0) && (i < n))
39195
<BR> ptr[i] = val;
39196
<BR> else {
39197
<BR> throw RangeError();
39198
<BR> }
39199
<BR> }
37508
39200
<BR> };
37509
39201
<BR></PRE>
37510
39202
</DIV>
37514
39206
<DIV class="code">
37515
39207
<PRE>%exception {
37516
39208
<BR> try {
37517
<BR> $action
39209
<BR> $action
37518
39210
<BR> }
37519
39211
<BR> catch (const RangeError&) {
37520
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
37521
<BR> rb_raise(cpperror, "Range error.");
39212
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
39213
<BR> rb_raise(cpperror, "Range error.");
37522
39214
<BR> }
37523
39215
<BR>}
37524
39216
<BR>
37538
39230
<DIV class="code">
37539
39231
<PRE>%exception getitem {
37540
39232
<BR> try {
37541
<BR> $action
39233
<BR> $action
37542
39234
<BR> }
37543
39235
<BR> catch (const RangeError&) {
37544
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
37545
<BR> rb_raise(cpperror, "Range error in getitem.");
39236
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
39237
<BR> rb_raise(cpperror, "Range error in getitem.");
37546
39238
<BR> }
37547
39239
<BR>}
37548
39240
<BR>
37549
39241
<BR>%exception setitem {
37550
39242
<BR> try {
37551
<BR> $action
39243
<BR> $action
37552
39244
<BR> }
37553
39245
<BR> catch (const RangeError&) {
37554
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
37555
<BR> rb_raise(cpperror, "Range error in setitem.");
39246
<BR> static VALUE cpperror = rb_define_class("CPPError", rb_eStandardError);
39247
<BR> rb_raise(cpperror, "Range error in setitem.");
37556
39248
<BR> }
37557
39249
<BR>}
37558
39250
<BR></PRE>
37562
39254
<P>Since SWIG's exception handling is user-definable, you are not
37563
39255
limited to C++ exception handling. See the chapter on <A href="#Customization">
37564
39256
Customization Features</A> for more examples.</P>
37565
<H3><A name="Ruby_nn35"></A>30.6.2 Raising exceptions</H3>
39257
<H3><A name="Ruby_nn34_2"></A>30.6.2 Handling Ruby Blocks</H3>
39258
<P>One of the highlights of Ruby and most of its standard library is the
39259
use of blocks, which allow the easy creation of continuations and other
39260
niceties. Blocks in ruby are also often used to simplify the passing
39261
of many arguments to a class.</P>
39262
<P>In order to make your class constructor support blocks, you can take
39263
advantage of the %exception directive, which will get run after the C++
39264
class' constructor was called. </P>
39265
<P>For example, this yields the class over after its construction:
39266
<BR></P>
39267
<DIV class="code">
39268
<PRE>class Window
39269
<BR>{
39270
<BR>public:
39271
<BR> Window(int x, int y, int w, int h);
39272
<BR>// .... other methods here ....
39273
<BR>};
39274
<BR>
39275
<BR>// Add support for yielding self in the Class' constructor.
39276
<BR>%exception Window::Window {
39277
<BR> $action
39278
<BR> if (rb_block_given_p()) {
39279
<BR> rb_yield(self);
39280
<BR> }
39281
<BR>}</PRE>
39282
</DIV>
39283
<P> Then, in ruby, it can be used like:</P>
39284
<DIV class="targetlang" style="font-family: monospace;">
39285
Window.new(0,0,360,480) { |w|
39286
<BR> w.color = Fltk::RED
39287
<BR> w.border = false
39288
<BR>
39289
<!--span class="targetlang"-->
39290
}</DIV>
39291
<BR>
39292
<P>For other methods, you can usually use a dummy parameter with a
39293
special in typemap, like:</P>
39294
<DIV class="code" style="font-family: monospace;">//
39295
<BR> // original function was:
39296
<BR> //
39297
<BR> // void func(int x);
39298
<BR>
39299
<BR> %typemap(in,numinputs=0) int RUBY_YIELD_SELF {
39300
<BR> if ( !rb_block_given_p() )
39301
<BR> rb_raise("No block given");
39302
<BR> return rb_yield(self);
39303
<BR> }
39304
<BR>
39305
<BR> %extend {
39306
<BR> void func(int x, int RUBY_YIELD_SELF );
39307
<BR> }</DIV>
39308
<P>For more information on typemaps, see <A href="#Ruby_nn37">Typemaps</A>
39309
.</P>
39310
<H3><A name="Ruby_nn35"></A>30.6.3 Raising exceptions</H3>
37566
39311
<P>There are three ways to raise exceptions from C++ code to Ruby.</P>
37567
39312
<P>The first way is to use <TT>SWIG_exception(int code, const char *msg)</TT>
37568
39313
. The following table shows the mappings from SWIG error codes to Ruby
37569
39314
exceptions:</P>
37570
<TABLE border="1" summary="Mapping between SWIG error codes and Ruby exceptions."
37571
width="80%">
37572
<TR><TD>SWIG_MemoryError</TD><TD>rb_eNoMemError</TD></TR>
37573
<TR><TD>SWIG_IOError</TD><TD>rb_eIOError</TD></TR>
37574
<TR><TD>SWIG_RuntimeError</TD><TD>rb_eRuntimeError</TD></TR>
37575
<TR><TD>SWIG_IndexError</TD><TD>rb_eIndexError</TD></TR>
37576
<TR><TD>SWIG_TypeError</TD><TD>rb_eTypeError</TD></TR>
37577
<TR><TD>SWIG_DivisionByZero</TD><TD>rb_eZeroDivError</TD></TR>
37578
<TR><TD>SWIG_OverflowError</TD><TD>rb_eRangeError</TD></TR>
37579
<TR><TD>SWIG_SyntaxError</TD><TD>rb_eSyntaxError</TD></TR>
37580
<TR><TD>SWIG_ValueError</TD><TD>rb_eArgError</TD></TR>
37581
<TR><TD>SWIG_SystemError</TD><TD>rb_eFatal</TD></TR>
37582
<TR><TD>SWIG_AttributeError</TD><TD>rb_eRuntimeError</TD></TR>
37583
<TR><TD>SWIG_NullReferenceError</TD><TD>rb_eNullReferenceError*</TD></TR>
37584
<TR><TD>SWIG_ObjectPreviouslyDeletedError</TD><TD>
37585
rb_eObjectPreviouslyDeleted*</TD></TR>
37586
<TR><TD>SWIG_UnknownError</TD><TD>rb_eRuntimeError</TD></TR>
37587
<TR><TD colspan="2">* These error classes are created by SWIG and are
37588
not built-in Ruby exception classes</TD></TR>
39315
<DIV class="diagram">
39316
<TABLE border="1" class="diagram" summary="Mapping between SWIG error codes and Ruby exceptions."
39317
width="80%"><TBODY></TBODY>
39318
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39319
SWIG_MemoryError</DIV></TD><TD style="font-family: monospace;"><DIV>
39320
rb_eNoMemError</DIV></TD></TR>
39321
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39322
SWIG_IOError</DIV></TD><TD style="font-family: monospace;"><DIV>
39323
rb_eIOError</DIV></TD></TR>
39324
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39325
SWIG_RuntimeError</DIV></TD><TD style="font-family: monospace;"><DIV>
39326
rb_eRuntimeError</DIV></TD></TR>
39327
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39328
SWIG_IndexError</DIV></TD><TD style="font-family: monospace;"><DIV>
39329
rb_eIndexError</DIV></TD></TR>
39330
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39331
SWIG_TypeError</DIV></TD><TD style="font-family: monospace;"><DIV>
39332
rb_eTypeError</DIV></TD></TR>
39333
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39334
SWIG_DivisionByZero</DIV></TD><TD style="font-family: monospace;"><DIV>
39335
rb_eZeroDivError</DIV></TD></TR>
39336
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39337
SWIG_OverflowError</DIV></TD><TD style="font-family: monospace;"><DIV>
39338
rb_eRangeError</DIV></TD></TR>
39339
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39340
SWIG_SyntaxError</DIV></TD><TD style="font-family: monospace;"><DIV>
39341
rb_eSyntaxError</DIV></TD></TR>
39342
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39343
SWIG_ValueError</DIV></TD><TD style="font-family: monospace;"><DIV>
39344
rb_eArgError</DIV></TD></TR>
39345
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39346
SWIG_SystemError</DIV></TD><TD style="font-family: monospace;"><DIV>
39347
rb_eFatal</DIV></TD></TR>
39348
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39349
SWIG_AttributeError</DIV></TD><TD style="font-family: monospace;"><DIV>
39350
rb_eRuntimeError</DIV></TD></TR>
39351
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39352
SWIG_NullReferenceError</DIV></TD><TD style="font-family: monospace;"><DIV>
39353
rb_eNullReferenceError*</DIV></TD></TR>
39354
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39355
SWIG_ObjectPreviouslyDeletedError</DIV></TD><TD style="font-family: monospace;">
39356
<DIV>rb_eObjectPreviouslyDeleted*</DIV></TD></TR>
39357
<TR><TD class="diagram" style="font-family: monospace;"><DIV>
39358
SWIG_UnknownError</DIV></TD><TD style="font-family: monospace;"><DIV>
39359
rb_eRuntimeError</DIV></TD></TR>
39360
<TR class="diagram" style="font-family: monospace;"><TD colspan="2"><DIV>
39361
* These error classes are created by SWIG and are not built-in Ruby
39362
exception classes</DIV></TD></TR>
37589
39363
</TABLE>
39364
</DIV>
37590
39365
<P>The second way to raise errors is to use <TT>SWIG_Raise(obj, type,
37591
39366
desc)</TT>. Obj is a C++ instance of an exception class, type is a
37592
39367
string specifying the type of exception (for example, "MyError") and
37593
39368
desc is the SWIG description of the exception class. For example:</P>
37594
<P> %raise(SWIG_NewPointerObj(e, SWIGTYPE_p_AssertionFailedException,
37595
0), ":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);</P>
39369
<DIV class="code" style="font-family: monospace;">
39370
%raise(SWIG_NewPointerObj(e, SWIGTYPE_p_AssertionFailedException, 0),
39371
":AssertionFailedException", SWIGTYPE_p_AssertionFailedException);</DIV>
37596
39372
<P>This is useful when you want to pass the current exception object
37597
39373
directly to Ruby, particularly when the object is an instance of class
37598
39374
marked as an <TT>%exceptionclass</TT> (see the next section for more
37602
39378
argument passed to <TT>rb_raise()</TT> is the exception type. You can
37603
39379
raise a custom exception type or one of the built-in Ruby exception
37604
39380
types.</P>
37605
<H3><A name="Ruby_nn36"></A>30.6.3 Exception classes</H3>
39381
<H3><A name="Ruby_nn36"></A>30.6.4 Exception classes</H3>
37606
39382
<P>Starting with SWIG 1.3.28, the Ruby module supports the <TT>
37607
39383
%exceptionclass</TT> directive, which is used to identify C++ classes
37608
39384
that are used as exceptions. Classes that are marked with the <TT>
37612
39388
C++ code and Ruby code.</P>
37613
39389
<DIV class="code">
37614
39390
<PRE> %exceptionclass CustomError;
37615
37616
%inline %{
37617
class CustomError { };
37618
37619
class Foo {
37620
<BR> public:
37621
<BR> void test() { throw CustomError; }
37622
};
37623
}
37624
</PRE>
39391
<BR>
39392
<BR> %inline %{
39393
<BR> class CustomError { };
39394
<BR>
39395
<BR> class Foo {
39396
<BR> public:
39397
<BR> void test() { throw CustomError; }
39398
<BR> };
39399
<BR> }
39400
<BR></PRE>
37625
39401
</DIV>
37626
<P>From Ruby you can now call this method like this:<DIV class="code">
39402
<P>From Ruby you can now call this method like this:</P>
39403
<DIV class="code targetlang">
37627
39404
<PRE>foo = Foo.new
37628
begin
37629
foo.test()
37630
rescue CustomError => e
37631
puts "Caught custom error"
37632
end </PRE>
37633
</DIV></P>
39405
<BR>begin
39406
<BR> foo.test()
39407
<BR>rescue CustomError => e
39408
<BR> puts "Caught custom error"
39409
<BR>end </PRE>
39410
</DIV>
37634
39411
<P>For another example look at swig/Examples/ruby/exception_class.
37635
39412
<BR></P>
37636
39413
<H2><A name="Ruby_nn37"></A>30.7 Typemaps</H2>
37638
39415
behavior for various C/C++ datatypes using the <TT>%typemap</TT>
37639
39416
directive. This is an advanced topic that assumes familiarity with the
37640
39417
Ruby C API as well as the material in the "<A href="#Typemaps">Typemaps</A>
37641
" chapter.</P>
39418
" chapter. </P>
37642
39419
<P>Before proceeding, it should be stressed that typemaps are not a
37643
39420
required part of using SWIG---the default wrapping behavior is enough
37644
39421
in most cases. Typemaps are only used if you want to change some aspect
37645
39422
of the primitive C-Ruby interface.</P>
37646
39423
<H3><A name="Ruby_nn38"></A>30.7.1 What is a typemap?</H3>
37647
39424
<P> A typemap is nothing more than a code generation rule that is
37648
attached to a specific C datatype. For example, to convert integers
37649
from Ruby to C, you might define a typemap like this:</P>
39425
attached to a specific C datatype. The general form of this declaration
39426
is as follows ( parts enclosed in [...] are optional ): </P>
39427
<DIV class="code">
39428
<!--span style="font-family: monospace;" class="code"-->
39429
%typemap( method [, modifiers...] ) typelist code;</DIV>
39430
<P><EM> method</EM> is a simply a name that specifies what kind of
39431
typemap is being defined. It is usually a name like <TT>"in"</TT>, <TT>
39432
"out"</TT>, or <TT>"argout"</TT> (or its director variations). The
39433
purpose of these methods is described later.</P>
39434
<P><EM> modifiers</EM> is an optional comma separated list of <TT>
39435
name="value"</TT> values. These are sometimes to attach extra
39436
information to a typemap and is often target-language dependent.</P>
39437
<P><EM> typelist</EM> is a list of the C++ type patterns that the
39438
typemap will match. The general form of this list is as follows:</P>
39439
<DIV class="diagram">
39440
<PRE>typelist : typepattern [, typepattern, typepattern, ... ] ;
39441
<BR>
39442
<BR>typepattern : type [ (parms) ]
39443
<BR> | type name [ (parms) ]
39444
<BR> | ( typelist ) [ (parms) ]
39445
<BR></PRE>
39446
</DIV>
39447
<P> Each type pattern is either a simple type, a simple type and
39448
argument name, or a list of types in the case of multi-argument
39449
typemaps. In addition, each type pattern can be parameterized with a
39450
list of temporary variables (parms). The purpose of these variables
39451
will be explained shortly.</P>
39452
<P><EM>code</EM> specifies the C code used in the typemap. It can take
39453
any one of the following forms:</P>
39454
<DIV class="diagram">
39455
<PRE>code : { ... }
39456
<BR> | " ... "
39457
<BR> | %{ ... %}
39458
<BR></PRE>
39459
</DIV>
39460
<P>For example, to convert integers from Ruby to C, you might define a
39461
typemap like this:</P>
37650
39462
<DIV class="code">
37651
39463
<PRE>%module example
37652
39464
<BR>
37670
39482
the input Ruby object.</P>
37671
39483
<P>When this example is compiled into a Ruby module, the following
37672
39484
sample code:</P>
37673
<DIV class="code">
39485
<DIV class="code targetlang">
37674
39486
<PRE>require 'example'
37675
39487
<BR>
37676
39488
<BR>puts Example.fact(6)
37677
39489
<BR></PRE>
37678
39490
</DIV>
37679
39491
<P>prints the result:</P>
37680
<DIV class="code">
39492
<DIV class="code shell">
37681
39493
<PRE>Received an integer : 6
37682
39494
<BR>720
37683
39495
<BR></PRE>
37733
39545
<P> When a multi-argument typemap is defined, the arguments are always
37734
39546
handled as a single Ruby object. This allows the function <TT>count</TT>
37735
39547
to be used as follows (notice how the length parameter is omitted):</P>
37736
<DIV class="code">
39548
<DIV class="code targetlang">
37737
39549
<PRE>puts Example.count('o','Hello World')
37738
39550
<BR>2
37739
39551
<BR></PRE>
37740
39552
</DIV>
37741
<H3><A name="Ruby_nn39"></A>30.7.2 Ruby typemaps</H3>
37742
<P> The previous section illustrated an "in" typemap for converting Ruby
37743
objects to C. A variety of different typemap methods are defined by the
37744
Ruby module. For example, to convert a C integer back into a Ruby
37745
object, you might define an "out" typemap like this:</P>
37746
<DIV class="code">
37747
<PRE>%typemap(out) int {
37748
<BR> $result = INT2NUM($1);
37749
<BR>}
37750
<BR></PRE>
37751
</DIV>
37752
<P> The following list details all of the typemap methods that can be
39553
<H3><A name="Ruby_Typemap_scope"></A>30.7.2 Typemap scope</H3>
39554
<P> Once defined, a typemap remains in effect for all of the
39555
declarations that follow. A typemap may be redefined for different
39556
sections of an input file. For example:</P>
39557
<DIV class="code">
39558
<PRE>// typemap1
39559
<BR>%typemap(in) int {
39560
<BR>...
39561
<BR>}
39562
<BR>
39563
<BR>int fact(int); // typemap1
39564
<BR>int gcd(int x, int y); // typemap1
39565
<BR>
39566
<BR>// typemap2
39567
<BR>%typemap(in) int {
39568
<BR>...
39569
<BR>}
39570
<BR>
39571
<BR>int isprime(int); // typemap2
39572
<BR></PRE>
39573
</DIV>
39574
<P> One exception to the typemap scoping rules pertains to the <TT>
39575
%extend</TT> declaration. <TT>%extend</TT> is used to attach new
39576
declarations to a class or structure definition. Because of this, all
39577
of the declarations in an <TT>%extend</TT> block are subject to the
39578
typemap rules that are in effect at the point where the class itself is
39579
defined. For example:</P>
39580
<DIV class="code">
39581
<PRE>class Foo {
39582
<BR> ...
39583
<BR>};
39584
<BR>
39585
<BR>%typemap(in) int {
39586
<BR> ...
39587
<BR>}
39588
<BR>
39589
<BR>%extend Foo {
39590
<BR> int blah(int x); // typemap has no effect. Declaration is attached to Foo which
39591
<BR> // appears before the %typemap declaration.
39592
<BR>};
39593
<BR></PRE>
39594
</DIV>
39595
<H3><A name="Ruby_Copying_a_typemap"></A>30.7.3 Copying a typemap</H3>
39596
<P> A typemap is copied by using assignment. For example:</P>
39597
<DIV class="code">
39598
<PRE>%typemap(in) Integer = int;
39599
<BR></PRE>
39600
</DIV>
39601
<P> or this:</P>
39602
<DIV class="code">
39603
<PRE>%typemap(in) Integer, Number, int32_t = int;
39604
<BR></PRE>
39605
</DIV>
39606
<P> Types are often managed by a collection of different typemaps. For
39607
example:</P>
39608
<DIV class="code">
39609
<PRE>%typemap(in) int { ... }
39610
<BR>%typemap(out) int { ... }
39611
<BR>%typemap(varin) int { ... }
39612
<BR>%typemap(varout) int { ... }
39613
<BR></PRE>
39614
</DIV>
39615
<P> To copy all of these typemaps to a new type, use <TT>%apply</TT>.
39616
For example:</P>
39617
<DIV class="code">
39618
<PRE>%apply int { Integer }; // Copy all int typemaps to Integer
39619
<BR>%apply int { Integer, Number }; // Copy all int typemaps to both Integer and Number
39620
<BR></PRE>
39621
</DIV>
39622
<P> The patterns for <TT>%apply</TT> follow the same rules as for <TT>
39623
%typemap</TT>. For example:</P>
39624
<DIV class="code">
39625
<PRE>%apply int *output { Integer *output }; // Typemap with name
39626
<BR>%apply (char *buf, int len) { (char *buffer, int size) }; // Multiple arguments
39627
<BR></PRE>
39628
</DIV>
39629
<H3><A name="Ruby_Deleting_a_typemap"></A>30.7.4 Deleting a typemap</H3>
39630
<P> A typemap can be deleted by simply defining no code. For example:</P>
39631
<DIV class="code">
39632
<PRE>%typemap(in) int; // Clears typemap for int
39633
<BR>%typemap(in) int, long, short; // Clears typemap for int, long, short
39634
<BR>%typemap(in) int *output;
39635
<BR></PRE>
39636
</DIV>
39637
<P> The <TT>%clear</TT> directive clears all typemaps for a given type.
39638
For example:</P>
39639
<DIV class="code">
39640
<PRE>%clear int; // Removes all types for int
39641
<BR>%clear int *output, long *output;
39642
<BR></PRE>
39643
</DIV>
39644
<P><B> Note:</B> Since SWIG's default behavior is defined by typemaps,
39645
clearing a fundamental type like <TT>int</TT> will make that type
39646
unusable unless you also define a new set of typemaps immediately after
39647
the clear operation.</P>
39648
<H3><A name="Ruby_Placement_of_typemaps"></A>30.7.5 Placement of
39649
typemaps</H3>
39650
<P> Typemap declarations can be declared in the global scope, within a
39651
C++ namespace, and within a C++ class. For example:</P>
39652
<DIV class="code">
39653
<PRE>%typemap(in) int {
39654
<BR> ...
39655
<BR>}
39656
<BR>
39657
<BR>namespace std {
39658
<BR> class string;
39659
<BR> %typemap(in) string {
39660
<BR> ...
39661
<BR> }
39662
<BR>}
39663
<BR>
39664
<BR>class Bar {
39665
<BR>public:
39666
<BR> typedef const int & const_reference;
39667
<BR> %typemap(out) const_reference {
39668
<BR> ...
39669
<BR> }
39670
<BR>};
39671
<BR></PRE>
39672
</DIV>
39673
<P> When a typemap appears inside a namespace or class, it stays in
39674
effect until the end of the SWIG input (just like before). However, the
39675
typemap takes the local scope into account. Therefore, this code</P>
39676
<DIV class="code">
39677
<PRE>namespace std {
39678
<BR> class string;
39679
<BR> %typemap(in) string {
39680
<BR> ...
39681
<BR> }
39682
<BR>}
39683
<BR></PRE>
39684
</DIV>
39685
<P> is really defining a typemap for the type <TT>std::string</TT>. You
39686
could have code like this:</P>
39687
<DIV class="code">
39688
<PRE>namespace std {
39689
<BR> class string;
39690
<BR> %typemap(in) string { /* std::string */
39691
<BR> ...
39692
<BR> }
39693
<BR>}
39694
<BR>
39695
<BR>namespace Foo {
39696
<BR> class string;
39697
<BR> %typemap(in) string { /* Foo::string */
39698
<BR> ...
39699
<BR> }
39700
<BR>}
39701
<BR></PRE>
39702
</DIV>
39703
<P> In this case, there are two completely distinct typemaps that apply
39704
to two completely different types (<TT>std::string</TT> and <TT>
39705
Foo::string</TT>).</P>
39706
<P> It should be noted that for scoping to work, SWIG has to know that <TT>
39707
string</TT> is a typename defined within a particular namespace. In this
39708
example, this is done using the class declaration <TT>class string</TT>
39709
.</P>
39710
<H3><A name="Ruby_nn39"></A>30.7.6 Ruby typemaps</H3>
39711
<P>The following list details all of the typemap methods that can be
37753
39712
used by the Ruby module:</P>
37754
<P><TT>%typemap(in)</TT></P>
37755
<DIV class="indent">Converts Ruby objects to input function arguments</DIV>
37756
<P><TT>%typemap(out)</TT></P>
37757
<DIV class="indent">Converts return value of a C function to a Ruby
37758
object</DIV>
37759
<P><TT>%typemap(varin)</TT></P>
37760
<DIV class="indent">Assigns a C global variable from a Ruby object</DIV>
37761
<P><TT>%typemap(varout)</TT></P>
37762
<DIV class="indent">Returns a C global variable as a Ruby object</DIV>
37763
<P><TT>%typemap(freearg)</TT></P>
37764
<DIV class="indent">Cleans up a function argument (if necessary)</DIV>
37765
<P><TT>%typemap(argout)</TT></P>
37766
<DIV class="indent">Output argument processing</DIV>
37767
<P><TT>%typemap(ret)</TT></P>
37768
<DIV class="indent">Cleanup of function return values</DIV>
37769
<P><TT>%typemap(memberin)</TT></P>
37770
<DIV class="indent">Setting of structure/class member data</DIV>
37771
<P><TT>%typemap(globalin)</TT></P>
37772
<DIV class="indent">Setting of C global variables</DIV>
37773
<P><TT>%typemap(check)</TT></P>
37774
<DIV class="indent">Checks function input values.</DIV>
37775
<P><TT>%typemap(default)</TT></P>
37776
<DIV class="indent">Set a default value for an argument (making it
37777
optional).</DIV>
37778
<P><TT>%typemap(arginit)</TT></P>
37779
<DIV class="indent">Initialize an argument to a value before any
37780
conversions occur.</DIV>
37781
<P> Examples of these typemaps appears in the <A href="#ruby_typemap_examples">
37782
section on typemap examples</A></P>
37783
<H3><A name="Ruby_nn40"></A>30.7.3 Typemap variables</H3>
37784
Within a typemap, a number of special variables prefaced with a <TT>$</TT>
37785
may appear. A full list of variables can be found in the "<A href="#Typemaps">
37786
Typemaps</A>" chapter. This is a list of the most common variables:
39713
<H4><A name="Ruby_in_typemap"></A>30.7.6.1 "in" typemap</H4>
39714
<P>Converts Ruby objects to input function arguments. For example:</P>
39715
<DIV class="code">
39716
<PRE>%typemap(in) int {
39717
<BR> $1 = NUM2INT($input);
39718
<BR>}
39719
<BR></PRE>
39720
</DIV>
39721
<P> The following special variables are available:</P>
39722
<DIV class="diagram">
39723
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Special variables - in typemap"
39724
width="100%"><TBODY></TBODY>
39725
<TR><TD style="font-family: monospace;">$input</TD><TD style="font-family: monospace;">
39726
Input object holding value to be converted.</TD></TR>
39727
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
39728
Name of function/method being wrapped</TD></TR>
39729
<TR><TD style="font-family: monospace;">$1...n</TD><TD style="font-family: monospace;">
39730
Argument being sent to the function</TD></TR>
39731
<TR><TD style="font-family: monospace;">$1_name</TD><TD style="font-family: monospace;">
39732
Name of the argument (if provided)</TD></TR>
39733
<TR><TD style="font-family: monospace;">$1_type</TD><TD style="font-family: monospace;">
39734
The actual C datatype matched by the typemap.</TD></TR>
39735
<TR><TD style="font-family: monospace;">$1_ltype</TD><TD style="font-family: monospace;">
39736
The assignable version of the C datatype matched by the typemap.</TD></TR>
39737
</TABLE>
39738
</DIV>
39739
<P> This is probably the most commonly redefined typemap because it can
39740
be used to implement customized conversions.</P>
39741
<P> In addition, the "in" typemap allows the number of converted
39742
arguments to be specified. For example:</P>
39743
<DIV class="code">
39744
<PRE>// Ignored argument.
39745
<BR>%typemap(in, numinputs=0) int *out (int temp) {
39746
<BR> $1 = &temp;
39747
<BR>}
39748
<BR></PRE>
39749
</DIV>
39750
<P> At this time, only zero or one arguments may be converted.</P>
39751
<H4><A name="Ruby_typecheck_typemap"></A>30.7.6.2 "typecheck" typemap</H4>
39752
<P> The "typecheck" typemap is used to support overloaded functions and
39753
methods. It merely checks an argument to see whether or not it matches
39754
a specific type. For example:</P>
39755
<DIV class="code">
39756
<PRE>%typemap(typecheck,precedence=SWIG_TYPECHECK_INTEGER) int {
39757
<BR> $1 = FIXNUM_P($input) ? 1 : 0;
39758
<BR>}
39759
<BR></PRE>
39760
</DIV>
39761
<P> For typechecking, the $1 variable is always a simple integer that is
39762
set to 1 or 0 depending on whether or not the input argument is the
39763
correct type.</P>
39764
<P> If you define new "in" typemaps<EM> and</EM> your program uses
39765
overloaded methods, you should also define a collection of "typecheck"
39766
typemaps. More details about this follow in a later section on
39767
"Typemaps and Overloading."</P>
39768
<H4><A name="Ruby_out_typemap"></A>30.7.6.3 "out" typemap</H4>
39769
<P>Converts return value of a C function to a Ruby object.</P>
39770
<DIV class="code"><TT>
39771
<BR> %typemap(out) int {
39772
<BR> $result = INT2NUM( $1 );
39773
<BR> }
39774
<BR></TT></DIV>
39775
<P> The following special variables are available.</P>
39776
<DIV class="diagram">
39777
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Special variables - out typemap"
39778
width="100%"><TBODY></TBODY>
39779
<TR><TD style="font-family: monospace;">$result</TD><TD style="font-family: monospace;">
39780
Result object returned to target language.</TD></TR>
39781
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
39782
Name of function/method being wrapped</TD></TR>
39783
<TR><TD style="font-family: monospace;">$1...n</TD><TD style="font-family: monospace;">
39784
Argument being wrapped</TD></TR>
39785
<TR><TD style="font-family: monospace;">$1_name</TD><TD style="font-family: monospace;">
39786
Name of the argument (if provided)</TD></TR>
39787
<TR><TD style="font-family: monospace;">$1_type</TD><TD style="font-family: monospace;">
39788
The actual C datatype matched by the typemap.</TD></TR>
39789
<TR><TD style="font-family: monospace;">$1_ltype</TD><TD style="font-family: monospace;">
39790
The assignable version of the C datatype matched by the typemap.</TD></TR>
39791
</TABLE>
39792
</DIV>
39793
<BR>
39794
<H4><A name="Ruby_arginit_typemap"></A>30.7.6.4 "arginit" typemap</H4>
39795
<P> The "arginit" typemap is used to set the initial value of a function
39796
argument--before any conversion has occurred. This is not normally
39797
necessary, but might be useful in highly specialized applications. For
39798
example:</P>
39799
<DIV class="code">
39800
<PRE>// Set argument to NULL before any conversion occurs
39801
<BR>%typemap(arginit) int *data {
39802
<BR> $1 = NULL;
39803
<BR>}
39804
<BR></PRE>
39805
</DIV>
39806
<H4><A name="Ruby_default_typemap"></A>30.7.6.5 "default" typemap</H4>
39807
<P> The "default" typemap is used to turn an argument into a default
39808
argument. For example:</P>
39809
<DIV class="code">
39810
<PRE>%typemap(default) int flags {
39811
<BR> $1 = DEFAULT_FLAGS;
39812
<BR>}
39813
<BR>...
39814
<BR>int foo(int x, int y, int flags);
39815
<BR></PRE>
39816
</DIV>
39817
<P> The primary use of this typemap is to either change the wrapping of
39818
default arguments or specify a default argument in a language where
39819
they aren't supported (like C). Target languages that do not support
39820
optional arguments, such as Java and C#, effectively ignore the value
39821
specified by this typemap as all arguments must be given.</P>
39822
<P> Once a default typemap has been applied to an argument, all
39823
arguments that follow must have default values. See the <A href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#SWIG_default_args">
39824
Default/optional arguments</A> section for further information on
39825
default argument wrapping.</P>
39826
<H4><A name="Ruby_check_typemap"></A>30.7.6.6 "check" typemap</H4>
39827
<P> The "check" typemap is used to supply value checking code during
39828
argument conversion. The typemap is applied<EM> after</EM> arguments
39829
have been converted. For example:</P>
39830
<DIV class="code">
39831
<PRE>%typemap(check) int positive {
39832
<BR> if ($1 <= 0) {
39833
<BR> SWIG_exception(SWIG_ValueError,"Expected positive value.");
39834
<BR> }
39835
<BR>}
39836
<BR></PRE>
39837
</DIV>
39838
<H4><A name="Ruby_argout_typemap_"></A>30.7.6.7 "argout" typemap</H4>
39839
<P> The "argout" typemap is used to return values from arguments. This
39840
is most commonly used to write wrappers for C/C++ functions that need
39841
to return multiple values. The "argout" typemap is almost always
39842
combined with an "in" typemap---possibly to ignore the input value. For
39843
example:</P>
39844
<DIV class="code">
39845
<PRE>/* Set the input argument to point to a temporary variable */
39846
<BR>%typemap(in, numinputs=0) int *out (int temp) {
39847
<BR> $1 = &temp;
39848
<BR>}
39849
<BR>
39850
<BR>%typemap(argout, fragment="output_helper") int *out {
39851
<BR> // Append output value $1 to $result (assuming a single integer in this case)
39852
<BR> $result = output_helper( $result, INT2NUM(*$1) );
39853
<BR>}
39854
<BR></PRE>
39855
</DIV>
39856
<P> The following special variables are available.</P>
39857
<DIV class="diagram">
39858
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Special variables - argout typemap"
39859
width="100%"><TBODY></TBODY>
39860
<TR><TD style="font-family: monospace;">$result</TD><TD style="font-family: monospace;">
39861
Result object returned to target language.</TD></TR>
39862
<TR><TD style="font-family: monospace;">$input</TD><TD style="font-family: monospace;">
39863
The original input object passed.</TD></TR>
39864
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
39865
Name of function/method being wrapped.</TD></TR>
39866
</TABLE>
39867
</DIV>
39868
<P> The code supplied to the "argout" typemap is always placed after the
39869
"out" typemap. If multiple return values are used, the extra return
39870
values are often appended to return value of the function.</P>
39871
<P>Output helper is a fragment that usually defines a macro to some
39872
function like SWIG_Ruby_AppendOutput.</P>
39873
<P> See the <TT>typemaps.i</TT> library for examples.</P>
39874
<H4><A name="Ruby_freearg_typemap_"></A>30.7.6.8 "freearg" typemap</H4>
39875
<P> The "freearg" typemap is used to cleanup argument data. It is only
39876
used when an argument might have allocated resources that need to be
39877
cleaned up when the wrapper function exits. The "freearg" typemap
39878
usually cleans up argument resources allocated by the "in" typemap. For
39879
example:</P>
39880
<DIV class="code">
39881
<PRE>// Get a list of integers
39882
<BR>%typemap(in) int *items {
39883
<BR> int nitems = Length($input);
39884
<BR> $1 = (int *) malloc(sizeof(int)*nitems);
39885
<BR>}
39886
<BR>// Free the list
39887
<BR>%typemap(freearg) int *items {
39888
<BR> free($1);
39889
<BR>}
39890
<BR></PRE>
39891
</DIV>
39892
<P> The "freearg" typemap inserted at the end of the wrapper function,
39893
just before control is returned back to the target language. This code
39894
is also placed into a special variable <TT>$cleanup</TT> that may be
39895
used in other typemaps whenever a wrapper function needs to abort
39896
prematurely.</P>
39897
<H4><A name="Ruby_newfree_typemap"></A>30.7.6.9 "newfree" typemap</H4>
39898
<P> The "newfree" typemap is used in conjunction with the <TT>%newobject</TT>
39899
directive and is used to deallocate memory used by the return result of
39900
a function. For example:</P>
39901
<DIV class="code">
39902
<PRE>%typemap(newfree) string * {
39903
<BR> delete $1;
39904
<BR>}
39905
<BR>%typemap(out) string * {
39906
<BR> $result = PyString_FromString($1->c_str());
39907
<BR>}
39908
<BR>...
39909
<BR>
39910
<BR>%newobject foo;
39911
<BR>...
39912
<BR>string *foo();
39913
<BR></PRE>
39914
</DIV>
39915
<P> See <A href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#ownership">
39916
Object ownership and %newobject</A> for further details.</P>
39917
<H4><A name="Ruby_memberin_typemap"></A>30.7.6.10 "memberin" typemap</H4>
39918
<P> The "memberin" typemap is used to copy data from<EM> an already
39919
converted input value</EM> into a structure member. It is typically
39920
used to handle array members and other special cases. For example:</P>
39921
<DIV class="code">
39922
<PRE>%typemap(memberin) int [4] {
39923
<BR> memmove($1, $input, 4*sizeof(int));
39924
<BR>}
39925
<BR></PRE>
39926
</DIV>
39927
<P> It is rarely necessary to write "memberin" typemaps---SWIG already
39928
provides a default implementation for arrays, strings, and other
39929
objects.</P>
39930
<H4><A name="Ruby_varin_typemap"></A>30.7.6.11 "varin" typemap</H4>
39931
<P> The "varin" typemap is used to convert objects in the target
39932
language to C for the purposes of assigning to a C/C++ global variable.
39933
This is implementation specific.</P>
39934
<H4><A name="Ruby_varout_typemap_"></A>30.7.6.12 "varout" typemap</H4>
39935
<P> The "varout" typemap is used to convert a C/C++ object to an object
39936
in the target language when reading a C/C++ global variable. This is
39937
implementation specific.</P>
39938
<H4><A name="Ruby_throws_typemap"></A>30.7.6.13 "throws" typemap</H4>
39939
<P> The "throws" typemap is only used when SWIG parses a C++ method with
39940
an exception specification or has the <TT>%catches</TT> feature
39941
attached to the method. It provides a default mechanism for handling
39942
C++ methods that have declared the exceptions they will throw. The
39943
purpose of this typemap is to convert a C++ exception into an error or
39944
exception in the target language. It is slightly different to the other
39945
typemaps as it is based around the exception type rather than the type
39946
of a parameter or variable. For example:</P>
39947
<DIV class="code">
39948
<PRE>%typemap(throws) const char * %{
39949
<BR> rb_raise(rb_eRuntimeError, $1);
39950
<BR> SWIG_fail;
39951
<BR>%}
39952
<BR>void bar() throw (const char *);
39953
<BR></PRE>
39954
</DIV>
39955
<P> As can be seen from the generated code below, SWIG generates an
39956
exception handler with the catch block comprising the "throws" typemap
39957
content.</P>
39958
<DIV class="code">
39959
<PRE>...
39960
<BR>try {
39961
<BR> bar();
39962
<BR>}
39963
<BR>catch(char const *_e) {
39964
<BR> rb_raise(rb_eRuntimeError, _e);
39965
<BR> SWIG_fail;
39966
<BR>}
39967
<BR>...
39968
<BR></PRE>
39969
</DIV>
39970
<P> Note that if your methods do not have an exception specification yet
39971
they do throw exceptions, SWIG cannot know how to deal with them. For a
39972
neat way to handle these, see the <A href="http://www.swig.org/Doc1.3/SWIGDocumentation.html#exception">
39973
Exception handling with %exception</A> section.</P>
39974
<H4><A name="Ruby_directorin_typemap"></A>30.7.6.14 directorin typemap</H4>
39975
<P>Converts C++ objects in director member functions to ruby objects. It
39976
is roughly the opposite of the "in" typemap, making its typemap rule
39977
often similar to the "out" typemap.</P>
39978
<DIV class="code"><TT>
39979
<BR> %typemap(directorin) int {
39980
<BR> $result = INT2NUM($1);
39981
<BR> }
39982
<BR></TT></DIV>
39983
<P> The following special variables are available.</P>
39984
<DIV class="diagram">
39985
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Special variables - directorin typemap"
39986
width="100%"><TBODY></TBODY>
39987
<TR><TD style="font-family: monospace;">$result</TD><TD style="font-family: monospace;">
39988
Result object returned to target language.</TD></TR>
39989
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
39990
Name of function/method being wrapped</TD></TR>
39991
<TR><TD style="font-family: monospace;">$1...n</TD><TD style="font-family: monospace;">
39992
Argument being wrapped</TD></TR>
39993
<TR><TD style="font-family: monospace;">$1_name</TD><TD style="font-family: monospace;">
39994
Name of the argument (if provided)</TD></TR>
39995
<TR><TD style="font-family: monospace;">$1_type</TD><TD style="font-family: monospace;">
39996
The actual C datatype matched by the typemap.</TD></TR>
39997
<TR><TD style="font-family: monospace;">$1_ltype</TD><TD style="font-family: monospace;">
39998
The assignable version of the C datatype matched by the typemap.</TD></TR>
39999
<TR><TD style="font-family: monospace;">this</TD><TD style="font-family: monospace;">
40000
C++ this, referring to the class itself.</TD></TR>
40001
</TABLE>
40002
</DIV>
40003
<H4><A name="Ruby_directorout_typemap"></A>30.7.6.15 directorout typemap</H4>
40004
<P>Converts Ruby objects in director member functions to C++ objects.
40005
It is roughly the opposite of the "out" typemap, making its rule often
40006
similar to the "in" typemap.</P>
40007
<DIV class="code"><TT style="font-family: monospace;">
40008
<BR> %typemap(directorout) int {</TT><TT>
40009
<BR> $result = NUM2INT($1);</TT>
40010
<BR> <TT style="font-family: monospace;">}
40011
<BR></TT></DIV>
40012
<P> The following special variables are available:</P>
40013
<DIV class="diagram">
40014
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Special variables - directorout typemap"
40015
width="100%"><TBODY></TBODY>
40016
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
40017
Name of function/method being wrapped</TD></TR>
40018
<TR><TD style="font-family: monospace;">$1...n</TD><TD style="font-family: monospace;">
40019
Argument being sent to the function</TD></TR>
40020
<TR><TD style="font-family: monospace;">$1_name</TD><TD style="font-family: monospace;">
40021
Name of the argument (if provided)</TD></TR>
40022
<TR><TD style="font-family: monospace;">$1_type</TD><TD style="font-family: monospace;">
40023
The actual C datatype matched by the typemap.</TD></TR>
40024
<TR><TD style="font-family: monospace;">$1_ltype</TD><TD style="font-family: monospace;">
40025
The assignable version of the C datatype matched by the typemap.</TD></TR>
40026
<TR><TD style="font-family: monospace;">this</TD><TD style="font-family: monospace;">
40027
C++ this, referring to the class itself.</TD></TR>
40028
</TABLE>
40029
</DIV>
40030
<P>Currently, the directorout nor the out typemap support the option
40031
<!--span style="font-family: monospace;"-->
40032
numoutputs, but the Ruby module provides that functionality through a
40033
%feature directive. Thus, a function can be made to return "nothing"
40034
if you do:</P>
40035
<DIV class="code" style="font-family: monospace;">
40036
%feature("numoutputs","0") MyClass::function;</DIV>
40037
<P>This feature can be useful if a function returns a status code, which
40038
you want to discard but still use the typemap to raise an exception.
40039
<BR></P>
40040
<H4><A name="Ruby_directorargout_typemap"></A>30.7.6.16 directorargout
40041
typemap</H4>
40042
<P>Output argument processing in director member functions.</P>
40043
<DIV class="code"><TT style="font-family: monospace;">
40044
%typemap(directorargout, fragment="output_helper") int {</TT><TT>
40045
<BR> $result = output_helper( $result, NUM2INT($1) );</TT>
40046
<BR> <TT style="font-family: monospace;">}</TT></DIV>
40047
<P> The following special variables are available:</P>
40048
<DIV class="diagram">
40049
<TABLE border="1" cellpadding="2" cellspacing="2" style="text-align: left; width: 100%;"
40050
summary="Special variables - directorargout typemap"><TBODY></TBODY>
40051
<TR><TD style="font-family: monospace;">$result</TD><TD style="font-family: monospace;">
40052
Result that the director function returns</TD></TR>
40053
<TR><TD style="font-family: monospace;">$symname</TD><TD style="font-family: monospace;">
40054
name of the function/method being wrapped</TD></TR>
40055
<TR><TD style="font-family: monospace;">$1...n</TD><TD style="font-family: monospace;">
40056
Argument being sent to the function</TD></TR>
40057
<TR><TD style="font-family: monospace;">$1_name</TD><TD style="font-family: monospace;">
40058
Name of the argument (if provided)</TD></TR>
40059
<TR><TD style="font-family: monospace;">$1_type</TD><TD style="font-family: monospace;">
40060
The actual C datatype matched by the typemap</TD></TR>
40061
<TR><TD style="font-family: monospace;">$1_ltype</TD><TD style="font-family: monospace;">
40062
The assignable version of the C datatype matched by the typemap</TD></TR>
40063
<TR><TD style="font-family: monospace;">this</TD><TD style="font-family: monospace;">
40064
C++ this, referring to the instance of the class itself</TD></TR>
40065
</TABLE>
40066
</DIV>
40067
<H4><A name="Ruby_ret_typemap"></A>30.7.6.17 ret typemap</H4>
40068
<P>Cleanup of function return values</P>
40069
<H4><A name="Ruby_globalin_typemap"></A>30.7.6.18 globalin typemap</H4>
40070
<P>Setting of C global variables</P>
40071
<H3><A name="Ruby_nn40"></A>30.7.7 Typemap variables</H3>
40072
<P> Within a typemap, a number of special variables prefaced with a <TT>
40073
$</TT> may appear. A full list of variables can be found in the "<A href="#Typemaps">
40074
Typemaps</A>" chapter. This is a list of the most common variables:</P>
37787
40075
<P><TT>$1</TT></P>
37788
40076
<DIV class="indent">A C local variable corresponding to the actual type
37789
40077
specified in the <TT>%typemap</TT> directive. For input values, this is
37809
40097
be properly assigned.</DIV>
37810
40098
<P><TT>$symname</TT></P>
37811
40099
<DIV class="indent">The Ruby name of the wrapper function being created.</DIV>
37812
<H3><A name="Ruby_nn41"></A>30.7.4 Useful Functions</H3>
40100
<H3><A name="Ruby_nn41"></A>30.7.8 Useful Functions</H3>
37813
40101
<P> When you write a typemap, you usually have to work directly with
37814
40102
Ruby objects. The following functions may prove to be useful. (These
37815
40103
functions plus many more can be found in <A href="http://www.rubycentral.com/book">
37816
<EM>Programming Ruby</EM></A>, by David Thomas and Andrew Hunt.)</P>
37817
<P> </P>
37818
<H4><A name="Ruby_nn42"></A>30.7.4.1 C Datatypes to Ruby Objects</H4>
37819
<DIV class="code">
37820
<PRE>INT2NUM(long or int) - int to Fixnum or Bignum
37821
<BR>INT2FIX(long or int) - int to Fixnum (faster than INT2NUM)
37822
<BR>CHR2FIX(char) - char to Fixnum
37823
<BR>rb_str_new2(char*) - char* to String
37824
<BR>rb_float_new(double) - double to Float
37825
<BR></PRE>
40104
<EM>Programming Ruby</EM></A>, by David Thomas and Andrew Hunt.) </P>
40105
<P>In addition, we list equivalent functions that Swig defines, which
40106
provide a language neutral conversion (these functions are defined for
40107
each swig language supported). If you are trying to create a swig file
40108
that will work under multiple languages, it is recommended you stick to
40109
the swig functions instead of the native Ruby functions. That should
40110
help you avoid having to rewrite a lot of typemaps across multiple
40111
languages.</P>
40112
<H4><A name="Ruby_nn42"></A>30.7.8.1 C Datatypes to Ruby Objects</H4>
40113
<DIV class="diagram">
40114
<TABLE border="1" cellpadding="2" cellspacing="2" style="width: 100%;" summary="Datatypes">
40115
<TBODY></TBODY>
40116
<TR><TH style="font-weight: bold;">RUBY</TH><TH style="font-weight: bold;">
40117
Swig</TH><TD></TD></TR>
40118
<TR><TD style="font-family: monospace;">INT2NUM(long or int)</TD><TD style="font-family: monospace;">
40119
SWIG_From_int(int x)</TD><TD> int to Fixnum or Bignum</TD></TR>
40120
<TR><TD style="font-family: monospace;">INT2FIX(long or int)</TD><TD style="font-family: monospace;">
40121
</TD><TD> int to Fixnum (faster than INT2NUM)</TD></TR>
40122
<TR><TD style="font-family: monospace;">CHR2FIX(char)</TD><TD style="font-family: monospace;">
40123
SWIG_From_char(char x)</TD><TD> char to Fixnum</TD></TR>
40124
<TR><TD style="font-family: monospace;">rb_str_new2(char*)</TD><TD style="font-family: monospace;">
40125
SWIG_FromCharPtrAndSize(char*, size_t)</TD><TD> char* to String</TD></TR>
40126
<TR><TD style="font-family: monospace;">rb_float_new(double)</TD><TD style="font-family: monospace;">
40127
SWIG_From_double(double),
40128
<BR> SWIG_From_float(float)</TD><TD>float/double to Float</TD></TR>
40129
</TABLE>
37826
40130
</DIV>
37827
<H4><A name="Ruby_nn43"></A>30.7.4.2 Ruby Objects to C Datatypes</H4>
37828
<DIV class="code">
37829
<PRE> int NUM2INT(Numeric)
37830
<BR> int FIX2INT(Numeric)
37831
<BR> unsigned int NUM2UINT(Numeric)
37832
<BR> unsigned int FIX2UINT(Numeric)
37833
<BR> long NUM2LONG(Numeric)
37834
<BR> long FIX2LONG(Numeric)
37835
<BR>unsigned long FIX2ULONG(Numeric)
37836
<BR> char NUM2CHR(Numeric or String)
37837
<BR> char * STR2CSTR(String)
37838
<BR> char * rb_str2cstr(String, int*length)
37839
<BR> double NUM2DBL(Numeric)
40131
<H4><A name="Ruby_nn43"></A>30.7.8.2 Ruby Objects to C Datatypes</H4>
40132
<P>Here, while the Ruby versions return the value directly, the SWIG
40133
versions do not, but return a status value to indicate success (
40134
<!--span style="font-family: monospace;"-->
40135
SWIG_OK). While more akward to use, this allows you to write typemaps
40136
that report more helpful error messages, like:</P>
40137
<DIV class="code" style="font-family: monospace;">
40138
<BR> %typemap(in) size_t (int ok)
40139
<BR>
40140
<BR> ok = SWIG_AsVal_size_t($input, &$1);
40141
<BR> if (!SWIG_IsOK(ok)) {
40142
<BR> SWIG_exception_fail(SWIG_ArgError(ok), Ruby_Format_TypeError(
40143
"$1_name", "$1_type","$symname", $argnum, $input ));
40144
<BR> }
37840
40145
<BR>
37841
<BR></PRE>
40146
<BR> }</DIV><DIV style="font-family: monospace;"> </DIV><DIV class="diagram">
40147
<TABLE border="1" cellpadding="2" cellspacing="2" summary="Ruby objects" width="100%">
40148
<TBODY></TBODY>
40149
<TR><TD style="font-family: monospace;">int NUM2INT(Numeric)</TD><TD style="font-family: monospace;">
40150
SWIG_AsVal_int(VALUE, int*)</TD></TR>
40151
<TR><TD style="font-family: monospace;">int FIX2INT(Numeric)</TD><TD style="font-family: monospace;">
40152
SWIG_AsVal_int(VALUE, int*)</TD></TR>
40153
<TR><TD style="font-family: monospace;">unsigned int NUM2UINT(Numeric)</TD><TD
40154
style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</TD>
40155
</TR>
40156
<TR><TD style="font-family: monospace;">unsigned int FIX2UINT(Numeric)</TD><TD
40157
style="font-family: monospace;">SWIG_AsVal_unsigned_SS_int(VALUE, int*)</TD>
40158
</TR>
40159
<TR><TD style="font-family: monospace;">long NUM2LONG(Numeric)</TD><TD style="font-family: monospace;">
40160
SWIG_AsVal_long(VALUE, long*)</TD></TR>
40161
<TR><TD style="font-family: monospace;">long FIX2LONG(Numeric)</TD><TD style="font-family: monospace;">
40162
SWIG_AsVal_long(VALUE, long*)</TD></TR>
40163
<TR><TD style="font-family: monospace;">unsigned long FIX2ULONG(Numeric)</TD><TD
40164
style="font-family: monospace;">SWIG_AsVal_unsigned_SS_long(VALUE,
40165
unsigned long*)</TD></TR>
40166
<TR><TD style="font-family: monospace;">char NUM2CHR(Numeric or String)</TD><TD
40167
style="font-family: monospace;">SWIG_AsVal_char(VALUE, int*)</TD></TR>
40168
<TR><TD style="font-family: monospace;">char * STR2CSTR(String)</TD><TD style="font-family: monospace;">
40169
SWIG_AsCharPtrAndSize(VALUE, char*, size_t, int* alloc)</TD></TR>
40170
<TR><TD style="font-family: monospace;">char * rb_str2cstr(String,
40171
int*length)</TD><TD style="font-family: monospace;"></TD></TR>
40172
<TR><TD style="font-family: monospace;">double NUM2DBL(Numeric)</TD><TD style="font-family: monospace;">
40173
(double) SWIG_AsVal_int(VALUE) or similar</TD></TR>
40174
</TABLE>
37842
40175
</DIV>
37843
<H4><A name="Ruby_nn44"></A>30.7.4.3 Macros for VALUE</H4>
37844
<P> <TT>RSTRING(str)->len</TT></P>
40176
<H4><A name="Ruby_nn44"></A>30.7.8.3 Macros for VALUE</H4>
40177
<P> <TT>RSTRING_LEN(str)</TT></P>
37845
40178
<DIV class="indent">length of the Ruby string</DIV>
37846
<P><TT>RSTRING(str)->ptr</TT></P>
40179
<P><TT>RSTRING_PTR(str)</TT></P>
37847
40180
<DIV class="indent">pointer to string storage</DIV>
37848
<P><TT>RARRAY(arr)->len</TT></P>
40181
<P><TT>RARRAY_LEN(arr)</TT></P>
37849
40182
<DIV class="indent">length of the Ruby array</DIV>
37850
40183
<P><TT>RARRAY(arr)->capa</TT></P>
37851
40184
<DIV class="indent">capacity of the Ruby array</DIV>
37852
<P><TT>RARRAY(arr)->ptr</TT></P>
40185
<P><TT>RARRAY_PTR(arr)</TT></P>
37853
40186
<DIV class="indent">pointer to array storage</DIV>
37854
<H4><A name="Ruby_nn45"></A>30.7.4.4 Exceptions</H4>
40187
<H4><A name="Ruby_nn45"></A>30.7.8.4 Exceptions</H4>
37855
40188
<P> <TT>void rb_raise(VALUE exception, const char *fmt, ...)</TT></P>
37856
40189
<DIV class="indent"> Raises an exception. The given format string<I> fmt</I>
37857
40190
and remaining arguments are interpreted as with <TT>printf()</TT>.</DIV>
37899
40232
error if Ruby was invoked with the <TT>-w</TT> flag. The given format
37900
40233
string<I> fmt</I> and remaining arguments are interpreted as with <TT>
37901
40234
printf()</TT>.</DIV>
37902
<H4><A name="Ruby_nn46"></A>30.7.4.5 Iterators</H4>
40235
<H4><A name="Ruby_nn46"></A>30.7.8.5 Iterators</H4>
37903
40236
<P> <TT>void rb_iter_break()</TT></P>
37904
40237
<DIV class="indent"> Breaks out of the enclosing iterator block.</DIV>
37905
40238
<P><TT>VALUE rb_each(VALUE obj)</TT></P>
37924
40257
<DIV class="indent"> Equivalent to Ruby's <TT>catch</TT>.</DIV>
37925
40258
<P><TT>void rb_throw(const char *tag, VALUE value)</TT></P>
37926
40259
<DIV class="indent"> Equivalent to Ruby's <TT>throw</TT>.</DIV>
37927
<H3><A name="Ruby_nn47"></A>30.7.5 Typemap Examples</H3>
40260
<H3><A name="Ruby_nn47"></A>30.7.9 Typemap Examples</H3>
37928
40261
<P> This section includes a few examples of typemaps. For more examples,
37929
40262
you might look at the examples in the <TT>Example/ruby</TT> directory.</P>
37930
<H3><A name="Ruby_nn48"></A>30.7.6 Converting a Ruby array to a char **</H3>
40263
<H3><A name="Ruby_nn48"></A>30.7.10 Converting a Ruby array to a char **</H3>
37931
40264
<P> A common problem in many C programs is the processing of command
37932
40265
line arguments, which are usually passed in an array of <TT>NULL</TT>
37933
40266
terminated strings. The following SWIG interface file allows a Ruby
37972
40305
</DIV>
37973
40306
<P> When this module is compiled, the wrapped C function now operates as
37974
40307
follows :</P>
37975
<DIV class="code">
40308
<DIV class="code targetlang">
37976
40309
<PRE>require 'Argv'
37977
40310
<BR>Argv.print_args(["Dave","Mike","Mary","Jane","John"])
37978
40311
<BR>argv[0] = Dave
37987
40320
dynamic memory allocation is used to allocate memory for the array, the
37988
40321
"freearg" typemap is used to later release this memory after the
37989
40322
execution of the C function.</P>
37990
<H3><A name="Ruby_nn49"></A>30.7.7 Collecting arguments in a hash</H3>
40323
<H3><A name="Ruby_nn49"></A>30.7.11 Collecting arguments in a hash</H3>
37991
40324
<P> Ruby's solution to the "keyword arguments" capability of some other
37992
40325
languages is to allow the programmer to pass in one or more key-value
37993
40326
pairs as arguments to a function. All of those key-value pairs are
38002
40335
</DIV>
38003
40336
<P> and you'd like to be able to call it from Ruby by passing in an
38004
40337
arbitrary number of key-value pairs as inputs, e.g.</P>
38005
<DIV class="code">
40338
<DIV class="code targetlang">
38006
40339
<PRE>setVitalStats("Fred",
38007
40340
<BR> 'weight' => 270,
38008
40341
<BR> 'age' => 42
38181
40514
<P> All of the code for this example, as well as a sample Ruby program
38182
40515
that uses the extension, can be found in the <TT>Examples/ruby/hashargs</TT>
38183
40516
directory of the SWIG distribution.</P>
38184
<H3><A name="Ruby_nn50"></A>30.7.8 Pointer handling</H3>
40517
<H3><A name="Ruby_nn50"></A>30.7.12 Pointer handling</H3>
38185
40518
<P> Occasionally, it might be necessary to convert pointer values that
38186
40519
have been stored using the SWIG typed-pointer representation. Since
38187
40520
there are several ways in which pointers can be represented, the
38213
40546
as information about converting pointer values under C++ inheritance.
38214
40547
For a type of <TT>Foo *</TT>, the type descriptor structure is usually
38215
40548
accessed as follows:</P>
38216
<DIV class="indent">
40549
<DIV class="indent code">
38217
40550
<PRE>Foo *foo;
38218
40551
<BR>SWIG_ConvertPtr($input, (void **) &foo, SWIGTYPE_p_Foo, 1);
38219
40552
<BR>
38223
40556
</DIV>
38224
40557
<P> In a typemap, the type descriptor should always be accessed using
38225
40558
the special typemap variable <TT>$1_descriptor</TT>. For example:</P>
38226
<DIV class="indent">
40559
<DIV class="indent code">
38227
40560
<PRE>%typemap(in) Foo * {
38228
40561
<BR> SWIG_ConvertPtr($input, (void **) &$1, $1_descriptor, 1);
38229
40562
<BR>}
38230
40563
<BR></PRE>
38231
40564
</DIV>
38232
<H4><A name="Ruby_nn51"></A>30.7.8.1 Ruby Datatype Wrapping</H4>
40565
<H4><A name="Ruby_nn51"></A>30.7.12.1 Ruby Datatype Wrapping</H4>
38233
40566
<P> <TT>VALUE Data_Wrap_Struct(VALUE class, void (*mark)(void *), void
38234
40567
(*free)(void *), void *ptr)</TT></P>
38235
40568
<DIV class="indent">Given a pointer<I> ptr</I> to some C data, and the
38244
40577
</P>
38245
40578
<DIV class="indent">Retrieves the original C pointer of type<I> c-type</I>
38246
40579
from the data object<I> obj</I> and assigns that pointer to<I> ptr</I>.</DIV>
38247
<H3><A name="Ruby_nn52"></A>30.7.9 Example: STL Vector to Ruby Array</H3>
38248
<P><EM><B>FIXME: This example is out of place here!</B></EM></P>
40580
<H3><A name="Ruby_nn52"></A>30.7.13 Example: STL Vector to Ruby Array</H3>
38249
40581
<P>Another use for macros and type maps is to create a Ruby array from a
38250
40582
STL vector of pointers. In essence, copy of all the pointers in the
38251
40583
vector into a Ruby array. The use of the macro is to make the typemap
38324
40656
<BR>%enddef
38325
40657
<BR></PRE>
38326
40658
</DIV>
38327
<H2><A name="Ruby_nn53"></A>30.8 Advanced Topics</H2>
38328
<H3><A name="Ruby_nn54"></A>30.8.1 Operator overloading</H3>
40659
<BR> Note that this is mostly an example of typemaps. If you want to use
40660
the STL with ruby, you are advised to use the standard swig STL
40661
library, which does much more than this. Refer to the section called
40662
the<A href="#Ruby_nn23_1"> C++ Standard Template Library</A>.
40663
<BR>
40664
<H2><A name="Ruby_nn65"></A>30.8 Docstring Features</H2>
40665
<P> Using ri and rdoc web pages in Ruby libraries is a common practice.
40666
Given the way that SWIG generates the extensions by default, your users
40667
will normally not get any documentation for it, even if they run 'rdoc'
40668
on the resulting .c or .cxx file.</P>
40669
<P>The features described in this section make it easy for you to add
40670
rdoc strings to your modules, functions and methods that can then be
40671
read by Ruby's rdoc tool to generate html web pages, ri documentation,
40672
Windows chm file and an .xml description.</P>
40673
<P>rdoc can then be run from a console or shell window on a swig
40674
generated file. </P>
40675
<P>For example, to generate html web pages from a C++ file, you'd do: </P>
40676
<DIV class="code shell">
40677
<!--span style="font-family: monospace; font-weight: bold;"-->
40678
$ rdoc -E cxx=c -f html file_wrap.cxx</DIV>
40679
<P>To generate ri documentation from a c wrap file, you could do:</P>
40680
<DIV class="code shell">
40681
<!--span style="font-family: monospace; font-weight: bold;"-->
40682
$ rdoc -r file_wrap.c</DIV>
40683
<H3><A name="Ruby_nn66"></A>30.8.1 Module docstring</H3>
40684
<P> Ruby allows a docstring at the beginning of the file before any
40685
other statements, and it is typically used to give a general
40686
description of the entire module. SWIG supports this by setting an
40687
option of the <TT>%module</TT> directive. For example:</P>
40688
<DIV class="code">
40689
<PRE>%module(docstring="This is the example module's docstring") example
40690
<BR></PRE>
40691
</DIV>
40692
<P> When you have more than just a line or so then you can retain the
40693
easy readability of the <TT>%module</TT> directive by using a macro.
40694
For example:</P>
40695
<DIV class="code">
40696
<PRE>%define DOCSTRING
40697
<BR>"The `XmlResource` class allows program resources defining menus,
40698
<BR>layout of controls on a panel, etc. to be loaded from an XML file."
40699
<BR>%enddef
40700
<BR>
40701
<BR>%module(docstring=DOCSTRING) xrc
40702
<BR></PRE>
40703
</DIV>
40704
<H3><A name="Ruby_nn67"></A>30.8.2 %feature("autodoc")</H3>
40705
<P>Since SWIG does know everything about the function it wraps, it is
40706
possible to generate an rdoc containing the parameter types, names and
40707
default values. Since Ruby ships with one of the best documentation
40708
systems of any language, it makes sense to take advantage of it.</P>
40709
<P>SWIG's Ruby module provides support for the "autodoc" feature, which
40710
when attached to a node in the parse tree will cause an rdoc comment to
40711
be generated in the wrapper file that includes the name of the
40712
function, parameter names, default values if any, and return type if
40713
any. There are also several options for autodoc controlled by the value
40714
given to the feature, described below.</P>
40715
<H4><A name="Ruby_nn68"></A>30.8.2.1 %feature("autodoc", "0")</H4>
40716
<P> When the "0" option is given then the types of the parameters will<EM>
40717
not</EM> be included in the autodoc string. For example, given this
40718
function prototype:</P>
40719
<DIV class="code">
40720
<PRE>%feature("autodoc", "0");
40721
<BR>bool function_name(int x, int y, Foo* foo=NULL, Bar* bar=NULL);
40722
<BR></PRE>
40723
</DIV>
40724
<P> Then Ruby code like this will be generated:</P>
40725
<DIV class="targetlang">
40726
<PRE>function_name(x, y, foo=nil, bar=nil) -> bool
40727
<BR> ...
40728
<BR></PRE>
40729
</DIV>
40730
<H4><A name="Ruby_autodoc1"></A>30.8.2.2 %feature("autodoc", "1")</H4>
40731
<P> When the "1" option is used then the parameter types<EM> will</EM>
40732
be used in the rdoc string. In addition, an attempt is made to simplify
40733
the type name such that it makes more sense to the Ruby user. Pointer,
40734
reference and const info is removed, <TT>%rename</TT>'s are evaluated,
40735
etc. (This is not always successful, but works most of the time. See
40736
the next section for what to do when it doesn't.) Given the example
40737
above, then turning on the parameter types with the "1" option will
40738
result in rdoc code like this:</P>
40739
<DIV class="targetlang">
40740
<PRE>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool
40741
<BR> ...
40742
<BR></PRE>
40743
</DIV>
40744
<H4><A name="Ruby_autodoc2"></A>30.8.2.3 %feature("autodoc", "2")</H4>
40745
<P> When the "2" option is used then the parameter types will not be
40746
used in the rdoc string. However, they will be listed in full after the
40747
function. Given the example above, then turning on the parameter types
40748
with the "2" option will result in Ruby code like this:</P>
40749
<H4><A name="Ruby_feature_autodoc3"></A>30.8.2.4 %feature("autodoc",
40750
"3")</H4>
40751
<P> When the "3" option is used then the function will be documented
40752
using a combination of "1" and "2" above. Given the example above,
40753
then turning on the parameter types with the "2" option will result in
40754
Ruby code like this:</P>
40755
<DIV class="targetlang">
40756
<PRE>function_name(int x, int y, Foo foo=nil, Bar bar=nil) -> bool
40757
<BR>
40758
<BR>Parameters:
40759
<BR> x - int
40760
<BR> y - int
40761
<BR> foo - Foo
40762
<BR> bar - Bar
40763
<BR></PRE>
40764
</DIV>
40765
<H4><A name="Ruby_nn70"></A>30.8.2.5 %feature("autodoc", "docstring")</H4>
40766
<P> Finally, there are times when the automatically generated autodoc
40767
string will make no sense for a Ruby programmer, particularly when a
40768
typemap is involved. So if you give an explicit value for the autodoc
40769
feature then that string will be used in place of the automatically
40770
generated string. For example:</P>
40771
<DIV class="code">
40772
<PRE>%feature("autodoc", "GetPosition() -> (x, y)") GetPosition;
40773
<BR>void GetPosition(int* OUTPUT, int* OUTPUT);
40774
<BR></PRE>
40775
</DIV>
40776
<H3><A name="Ruby_nn71"></A>30.8.3 %feature("docstring")</H3>
40777
<P> In addition to the autodoc strings described above, you can also
40778
attach any arbitrary descriptive text to a node in the parse tree with
40779
the "docstring" feature. When the proxy module is generated then any
40780
docstring associated with classes, function or methods are output. If
40781
an item already has an autodoc string then it is combined with the
40782
docstring and they are output together.</P>
40783
<H2><A name="Ruby_nn53"></A>30.9 Advanced Topics</H2>
40784
<H3><A name="Ruby_nn54"></A>30.9.1 Operator overloading</H3>
38329
40785
<P> SWIG allows operator overloading with, by using the <TT>%extend</TT>
38330
40786
or <TT>%rename</TT> commands in SWIG and the following operator names
38331
40787
(derived from Python):</P>
38332
<DIV class="code">
38333
<PRE><B> General</B>
38334
<BR>__repr__ - inspect
38335
<BR>__str__ - to_s
38336
<BR>__cmp__ - <=>
38337
<BR>__hash__ - hash
38338
<BR>__nonzero__ - nonzero?
38339
<BR>
38340
<BR><B> Callable</B>
38341
<BR>__call__ - call
38342
<BR>
38343
<BR><B> Collection</B>
38344
<BR>__len__ - length
38345
<BR>__getitem__ - []
38346
<BR>__setitem__ - []=
38347
<BR>
38348
<BR><B> Numeric</B>
38349
<BR>__add__ - +
38350
<BR>__sub__ - -
38351
<BR>__mul__ - *
38352
<BR>__div__ - /
38353
<BR>__mod__ - %
38354
<BR>__divmod__ - divmod
38355
<BR>__pow__ - **
38356
<BR>__lshift__ - <<
38357
<BR>__rshift__ - >>
38358
<BR>__and__ - &
38359
<BR>__xor__ - ^
38360
<BR>__or__ - |
38361
<BR>__neg__ - -@
38362
<BR>__pos__ - +@
38363
<BR>__abs__ - abs
38364
<BR>__invert__ - ~
38365
<BR>__int__ - to_i
38366
<BR>__float__ - to_f
38367
<BR>__coerce__ - coerce
38368
<BR>
38369
<BR><B>Additions in 1.3.13 </B>
38370
<BR>__lt__ - <
38371
<BR>__le__ - <=
38372
<BR>__eq__ - ==
38373
<BR>__gt__ - >
38374
<BR>__ge__ - >=
38375
<BR>
38376
<BR></PRE>
40788
<DIV class="code diagram">
40789
<TABLE border="1" cellpadding="2" cellspacing="2" style="width: 100%; font-family: monospace;"
40790
summary="operator names"><TBODY></TBODY>
40791
<TR><TD><B> General</B></TD></TR>
40792
<TR><TD>__repr__</TD><TD> inspect</TD></TR>
40793
<TR><TD>__str__</TD><TD> to_s</TD></TR>
40794
<TR><TD>__cmp__</TD><TD> <=></TD></TR>
40795
<TR><TD>__hash__</TD><TD> hash</TD></TR>
40796
<TR><TD>__nonzero__</TD><TD> nonzero?</TD></TR>
40797
<TR><TD></TD></TR>
40798
<TR><TD><B> Callable</B></TD></TR>
40799
<TR><TD>__call__</TD><TD> call</TD></TR>
40800
<TR><TD></TD></TR>
40801
<TR><TD><B> Collection</B></TD></TR>
40802
<TR><TD>__len__</TD><TD> length</TD></TR>
40803
<TR><TD>__getitem__</TD><TD> []</TD></TR>
40804
<TR><TD>__setitem__</TD><TD> []=</TD></TR>
40805
<TR><TD></TD></TR>
40806
<TR><TD><B> Numeric</B></TD></TR>
40807
<TR><TD>__add__</TD><TD> +</TD></TR>
40808
<TR><TD>__sub__</TD><TD> -</TD><TD></TD></TR>
40809
<TR><TD>__mul__</TD><TD> *</TD></TR>
40810
<TR><TD>__div__</TD><TD> /</TD></TR>
40811
<TR><TD>__mod__</TD><TD> %</TD></TR>
40812
<TR><TD>__divmod__</TD><TD> divmod</TD></TR>
40813
<TR><TD>__pow__</TD><TD> **</TD></TR>
40814
<TR><TD>__lshift__</TD><TD> <<</TD></TR>
40815
<TR><TD>__rshift__</TD><TD> >></TD></TR>
40816
<TR><TD>__and__</TD><TD> &</TD></TR>
40817
<TR><TD>__xor__</TD><TD> ^</TD></TR>
40818
<TR><TD>__or__</TD><TD> |</TD></TR>
40819
<TR><TD>__neg__</TD><TD> -@</TD><TD></TD></TR>
40820
<TR><TD>__pos__</TD><TD> +@</TD></TR>
40821
<TR><TD>__abs__</TD><TD> abs</TD></TR>
40822
<TR><TD>__invert__</TD><TD> ~</TD></TR>
40823
<TR><TD>__int__</TD><TD> to_i</TD></TR>
40824
<TR><TD>__float__</TD><TD> to_f</TD></TR>
40825
<TR><TD>__coerce__</TD><TD> coerce</TD></TR>
40826
<TR><TD></TD></TR>
40827
<TR><TD><B>Additions in 1.3.13</B></TD></TR>
40828
<TR><TD>__lt__</TD><TD> <</TD></TR>
40829
<TR><TD>__le__</TD><TD> <=</TD></TR>
40830
<TR><TD>__eq__</TD><TD> ==</TD></TR>
40831
<TR><TD>__gt__</TD><TD> ></TD></TR>
40832
<TR><TD>__ge__</TD><TD> >=</TD></TR>
40833
</TABLE>
38377
40834
</DIV>
38378
40835
<P> Note that although SWIG supports the <TT>__eq__</TT> magic method
38379
40836
name for defining an equivalence operator, there is no separate method
38380
40837
for handling<I> inequality</I> since Ruby parses the expression<I> a !=
38381
40838
b</I> as<I> !(a == b)</I>.</P>
38382
<H3><A name="Ruby_nn55"></A>30.8.2 Creating Multi-Module Packages</H3>
40839
<H3><A name="Ruby_nn55"></A>30.9.2 Creating Multi-Module Packages</H3>
38383
40840
<P> The chapter on <A href="Modules.html">Working with Modules</A>
38384
40841
discusses the basics of creating multi-module extensions with SWIG, and
38385
40842
in particular the considerations for sharing runtime type information
38428
40885
<BR></PRE>
38429
40886
</DIV>
38430
40887
<P> We'll start by building the<B> Shape</B> extension module:</P>
38431
<DIV class="code">
40888
<DIV class="code shell">
38432
40889
<PRE>$ <B>swig -c++ -ruby shape.i</B>
38433
40890
</PRE>
38434
40891
</DIV>
38435
40892
<P> SWIG generates a wrapper file named <TT>shape_wrap.cxx</TT>. To
38436
40893
compile this into a dynamically loadable extension for Ruby, prepare an
38437
40894
<TT>extconf.rb</TT> script using this template:</P>
38438
<DIV class="code">
40895
<DIV class="code targetlang">
38439
40896
<PRE>require 'mkmf'
38440
40897
<BR>
38441
40898
<BR># Since the SWIG runtime support library for Ruby
38449
40906
</DIV>
38450
40907
<P> Run this script to create a <TT>Makefile</TT> and then type <TT>make</TT>
38451
40908
to build the shared library:</P>
38452
<DIV class="code">
40909
<DIV class="code targetlang">
38453
40910
<PRE>$ <B>ruby extconf.rb</B>
38454
40911
<BR>creating Makefile
38455
40912
<BR>$ <B>make</B>
38475
40932
<P> Once you've built both of these extension modules, you can test them
38476
40933
interactively in IRB to confirm that the <TT>Shape</TT> and <TT>Circle</TT>
38477
40934
modules are properly loaded and initialized:</P>
38478
<DIV class="code">
40935
<DIV class="code targetlang">
38479
40936
<PRE>$ <B>irb</B>
38480
40937
<BR>irb(main):001:0> <B>require 'shape'</B>
38481
40938
<BR>true
38489
40946
<BR>5.0
38490
40947
<BR></PRE>
38491
40948
</DIV>
38492
<H3><A name="Ruby_nn56"></A>30.8.3 Specifying Mixin Modules</H3>
40949
<H3><A name="Ruby_nn56"></A>30.9.3 Specifying Mixin Modules</H3>
38493
40950
<P> The Ruby language doesn't support multiple inheritance, but it does
38494
40951
allow you to mix one or more modules into a class using Ruby's <TT>
38495
40952
include</TT> method. For example, if you have a Ruby class that defines
38496
40953
an<EM> each</EM> instance method, e.g.</P>
38497
<DIV class="code">
40954
<DIV class="code targetlang">
38498
40955
<PRE>class Set
38499
40956
<BR> def initialize
38500
40957
<BR> @members = []
38508
40965
</DIV>
38509
40966
<P> then you can mix-in Ruby's <TT>Enumerable</TT> module to easily add
38510
40967
a lot of functionality to your class:</P>
38511
<DIV class="code">
40968
<DIV class="code targetlang">
38512
40969
<PRE>class Set
38513
40970
<BR> <B>include Enumerable</B>
38514
40971
<BR>def initialize
38547
41004
"features" mechanism and so the same name matching rules used for other
38548
41005
kinds of features apply (see the chapter on <A href="#Customization">
38549
41006
"Customization Features"</A>) for more details).</P>
38550
<H2><A name="Ruby_nn57"></A>30.9 Memory Management</H2>
41007
<H2><A name="Ruby_nn57"></A>30.10 Memory Management</H2>
38551
41008
<P>One of the most common issues in generating SWIG bindings for Ruby is
38552
41009
proper memory management. The key to proper memory management is
38553
41010
clearly defining whether a wrapper Ruby object owns the underlying C
38562
41019
(or vice versa) depending on what function or methods are invoked.
38563
41020
Clearly, developing a SWIG wrapper requires a thorough understanding of
38564
41021
how the underlying library manages memory.</P>
38565
<H3><A name="Ruby_nn58"></A>30.9.1 Mark and Sweep Garbage Collector</H3>
41022
<H3><A name="Ruby_nn58"></A>30.10.1 Mark and Sweep Garbage Collector</H3>
38566
41023
<P>Ruby uses a mark and sweep garbage collector. When the garbage
38567
41024
collector runs, it finds all the "root" objects, including local
38568
41025
variables, global variables, global constants, hardware registers and
38590
41047
memory has been allocated in creating the underlying C struct or C++
38591
41048
struct, then a "free" function must be defined that deallocates this
38592
41049
memory.</P>
38593
<H3><A name="Ruby_nn59"></A>30.9.2 Object Ownership</H3>
41050
<H3><A name="Ruby_nn59"></A>30.10.2 Object Ownership</H3>
38594
41051
<P>As described above, memory management depends on clearly defining who
38595
41052
is responsible for freeing the underlying C struct or C++ class. If the
38596
41053
Ruby object is responsible for freeing the C++ object, then a "free"
38630
41087
<BR> void set_foo(Foo *foo) { delete foo_; foo_ = foo; }
38631
41088
<BR>};
38632
41089
<BR>
38633
</PRE>
41090
<BR></PRE>
38634
41091
</DIV>
38635
41092
<P>First, consider this Ruby code:</P>
38636
<DIV class="code">
41093
<DIV class="code targetlang">
38637
41094
<PRE>foo = Foo.new</PRE>
38638
41095
</DIV>
38639
41096
<P>In this case, the Ruby code calls the underlying <TT>Foo</TT> C++
38642
41099
is garbage collected, the "free" function will be called. It in turn
38643
41100
will call <TT>Foo's</TT> destructor.</P>
38644
41101
<P>Next, consider this code:</P>
38645
<DIV class="code">
41102
<DIV class="code targetlang">
38646
41103
<PRE>bar = Bar.new
38647
41104
<BR>foo = bar.get_foo()</PRE>
38648
41105
</DIV>
38652
41109
foo</TT> object is not affected.</P>
38653
41110
<P>Unfortunately, the real world is not as simple as the examples above.
38654
41111
For example:</P>
38655
<DIV class="code">
41112
<DIV class="code targetlang">
38656
41113
<PRE>bar = Bar.new
38657
41114
<BR>foo = bar.get_new_foo()</PRE>
38658
41115
</DIV>
38661
41118
object. This can be done by using the %newobject directive. See <A href="#ownership">
38662
41119
Object ownership and %newobject</A> for more information.</P>
38663
41120
<P>The SWIG default mappings are also incorrect in this case:</P>
38664
<DIV class="code">
41121
<DIV class="code targetlang">
38665
41122
<PRE>foo = Foo.new
38666
41123
<BR>bar = Bar.new
38667
41124
<BR>bar.set_foo(foo)</PRE>
38714
41171
%clear Foo *foo;
38715
41172
<BR>};
38716
41173
<BR>
38717
</PRE>
41174
<BR></PRE>
38718
41175
</DIV>
38719
41176
<BR>
38720
41177
<P> This code can be seen in swig/examples/ruby/tracking.</P>
38721
41178
<BR>
38722
<H3><A name="Ruby_nn60"></A>30.9.3 Object Tracking</H3>
41179
<H3><A name="Ruby_nn60"></A>30.10.3 Object Tracking</H3>
38723
41180
<P>The remaining parts of this section will use the class library shown
38724
41181
below to illustrate different memory management techniques. The class
38725
41182
library models a zoo and the animals it contains.</P>
38790
41247
<BR> }
38791
41248
<BR>};
38792
41249
<BR>
38793
</PRE>
41250
<BR></PRE>
38794
41251
</DIV>
38795
41252
<P>Let's say you SWIG this code and then run IRB:
38796
41253
<BR></P>
38797
<DIV class="code">
41254
<DIV class="code targetlang">
38798
41255
<PRE>$
38799
41256
<!--span style="font-weight: bold;"-->
38800
41257
irb
38843
41300
tiger1.equal?(tiger2)
38844
41301
<BR>=> false
38845
41302
<BR>
38846
</PRE>
41303
<BR></PRE>
38847
41304
</DIV>
38848
41305
<P>Pay particular attention to the code <TT>tiger1.equal?(tiger2)</TT>.
38849
41306
Note that the two Ruby objects are not the same - but they reference
38850
41307
the same underlying C++ object. This can cause problems. For example:
38851
41308
<BR></P>
38852
<DIV class="code">
41309
<DIV class="code targetlang">
38853
41310
<PRE>irb(main):010:0>
38854
41311
<!--span style="font-weight: bold;"-->
38855
41312
tiger1 = nil
38865
41322
tiger2.get_name()
38866
41323
<BR>(irb):12: [BUG] Segmentation fault
38867
41324
<BR>
38868
</PRE>
41325
<BR></PRE>
38869
41326
</DIV>
38870
41327
<P>After the the garbage collector runs, as a result of our call to <TT>
38871
41328
GC.start</TT>, calling<TT>tiger2.get_name()</TT> causes a segmentation
38912
41369
<P>When this code runs we see:
38913
41370
<BR>
38914
41371
<BR></P>
38915
<DIV class="code">
41372
<DIV class="code targetlang">
38916
41373
<PRE>$
38917
41374
<!--span style="font-weight: bold;"-->
38918
41375
irb
38962
41419
<BR>=> "tiger1"
38963
41420
<BR>irb(main):011:0>
38964
41421
<BR>
38965
</PRE>
41422
<BR></PRE>
38966
41423
</DIV>
38967
41424
<P>For those who are interested, object tracking is implemented by
38968
41425
storing Ruby objects in a hash table and keying them on C++ pointers.
38984
41441
<P>In general, you will only need to use the <TT>SWIG_RubyInstanceFor</TT>
38985
41442
, which is required for implementing mark functions as shown below.
38986
41443
However, if you implement your own free functions (see below) you may
38987
also have to call the<TT>SWIG_RubyRemoveTracking</TT> and <TT>
41444
also have to call the <TT>SWIG_RubyRemoveTracking</TT> and <TT>
38988
41445
RubyUnlinkObjects</TT> methods.</P>
38989
<H3><A name="Ruby_nn61"></A>30.9.4 Mark Functions</H3>
41446
<H3><A name="Ruby_nn61"></A>30.10.4 Mark Functions</H3>
38990
41447
<P>With a bit more testing, we see that our class library still has
38991
41448
problems. For example:
38992
41449
<BR></P>
38993
<DIV class="code">
41450
<DIV class="targetlang">
38994
41451
<PRE>$ <B>irb</B>
38995
41452
<BR>irb(main):001:0>
38996
41453
<!--span style="font-weight: bold;"-->
39041
41498
<P>A <TT>mark</TT> function takes a single argument, which is a pointer
39042
41499
to the C++ object being marked; it should, in turn, call <TT>
39043
41500
rb_gc_mark()</TT> for any instances that are reachable from the current
39044
object. The mark function for our <TT> Zoo</TT> class should therefore
41501
object. The mark function for our <TT>Zoo</TT> class should therefore
39045
41502
loop over all of the C++ animal objects in the zoo object, look up
39046
41503
their Ruby object equivalent, and then call <TT>rb_gc_mark()</TT>. One
39047
41504
possible implementation is:</P>
39075
41532
<BR> int count = zoo->get_num_animals();
39076
41533
<BR>
39077
41534
<BR> for(int i = 0; i < count; ++i) {
39078
<BR> Animal* animal = zoo->get_animal(i);
39079
<BR> VALUE object = SWIG_RubyInstanceFor(animal);
41535
<BR> Animal* animal = zoo->get_animal(i);
41536
<BR> VALUE object = SWIG_RubyInstanceFor(animal);
39080
41537
<BR>
39081
<BR> if (object != Qnil) {
39082
<BR> rb_gc_mark(object);
39083
<BR> }
41538
<BR> if (object != Qnil) {
41539
<BR> rb_gc_mark(object);
41540
<BR> }
39084
41541
<BR> }
39085
41542
<BR>}
39086
41543
<BR>%}
39087
41544
<BR>
39088
</PRE>
41545
<BR></PRE>
39089
41546
</DIV>
39090
41547
<P> Note the <TT>mark</TT> function is dependent on the <TT>
39091
41548
SWIG_RUBY_InstanceFor</TT> method, and thus requires that <TT>
39092
41549
%trackobjects</TT> is enabled. For more information, please refer to the
39093
41550
track_object.i test case in the SWIG test suite.</P>
39094
41551
<P>When this code is compiled we now see:</P>
39095
<DIV class="code">
41552
<DIV class="targetlang">
39096
41553
<PRE>$ <B>irb
39097
41554
<BR></B>irb(main):002:0>
39098
41555
<!--span style="font-weight: bold;"-->
39134
41591
<BR>=> "tiger1"
39135
41592
<BR>irb(main):016:0>
39136
41593
<BR>
39137
</PRE>
41594
<BR></PRE>
39138
41595
</DIV>
39139
41596
<BR>
39140
41597
<P>This code can be seen in swig/examples/ruby/mark_function.</P>
39141
<H3><A name="Ruby_nn62"></A>30.9.5 Free Functions</H3>
41598
<H3><A name="Ruby_nn62"></A>30.10.5 Free Functions</H3>
39142
41599
<P>By default, SWIG creates a "free" function that is called when a Ruby
39143
41600
object is garbage collected. The free function simply calls the C++
39144
41601
object's destructor.</P>
39181
41638
<BR>}</PRE>
39182
41639
</DIV>
39183
41640
<P>When we use these objects in IRB we see:</P>
39184
<DIV class="code">
39185
<PRE>
41641
<DIV class="code targetlang">
41642
<PRE class="targetlang">
39186
41643
<!--span style="font-weight: bold;"-->
39187
41644
$irb
39188
41645
<BR>irb(main):002:0>
39220
41677
tiger1.get_name()
39221
41678
<BR>(irb):12: [BUG] Segmentation fault
39222
41679
<BR>
39223
</PRE>
41680
<BR></PRE>
39224
41681
</DIV>
39225
41682
<P>The error happens because the C++ <TT>animal</TT> object is freed
39226
41683
when the <TT>zoo</TT> object is freed. Although this error is
39279
41736
<BR>%} </PRE>
39280
41737
</DIV>
39281
41738
<P>Now when we use these objects in IRB we see:</P>
39282
<DIV class="code">
41739
<DIV class="code targetlang">
39283
41740
<PRE>
39284
41741
<!--span style="font-weight: bold;"-->
39285
41742
$irb
39324
41781
<P>Notice that SWIG can now detect the underlying C++ object has been
39325
41782
freed, and thus raises a runtime exception.</P>
39326
41783
<P>This code can be seen in swig/examples/ruby/free_function.</P>
41784
<H3><A name="Ruby_nn63"></A>30.10.6 Embedded Ruby and the C++ Stack</H3>
41785
<P>As has been said, the Ruby GC runs and marks objects before its sweep
41786
phase. When the garbage collector is called, it will also try to mark
41787
any Ruby objects (VALUE) it finds in the machine registers and in the
41788
C++ stack.</P>
41789
<P>The stack is basically the history of the functions that have been
41790
called and also contains local variables, such as the ones you define
41791
whenever you do inside a function:</P>
41792
<DIV class="diagram">VALUE obj;</DIV>
41793
<P>For ruby to determine where its stack space begins, during
41794
initialization a normal Ruby interpreter will call the ruby_init()
41795
function which in turn will call a function called Init_stack or
41796
similar. This function will store a pointer to the location where the
41797
stack points at at that point in time.</P>
41798
<P>ruby_init() is presumed to always be called within the main()
41799
function of your program and whenever the GC is called, ruby will
41800
assume that the memory between the current location in memory and the
41801
pointer that was stored previously represents the stack, which may
41802
contain local (and temporary) VALUE ruby objects. Ruby will then be
41803
careful not to remove any of those objects in that location.</P>
41804
<P>So far so good. For a normal Ruby session, all the above is
41805
completely transparent and magic to the extensions developer. </P>
41806
<P>However, with an embedded Ruby, it may not always be possible to
41807
modify main() to make sure ruby_init() is called there. As such,
41808
ruby_init() will likely end up being called from within some other
41809
function. This can lead Ruby to measure incorrectly where the stack
41810
begins and can result in Ruby incorrectly collecting those temporary
41811
VALUE objects that are created once another function is called. The
41812
end result: random crashes and segmentation faults.</P>
41813
<P>This problem will often be seen in director functions that are used
41814
for callbacks, for example. </P>
41815
<P>To solve the problem, SWIG can now generate code with director
41816
functions containing the optional macros SWIG_INIT_STACK and
41817
SWIG_RELEASE_STACK. These macros will try to force Ruby to
41818
reinitiliaze the beginning of the stack the first time a director
41819
function is called. This will lead Ruby to measure and not collect any
41820
VALUE objects defined from that point on. </P>
41821
<P>To mark functions to either reset the ruby stack or not, you can use:</P>
41822
<DIV class="indent code" style="font-family: monospace;">%initstack
41823
Class::memberfunction; // only re-init the stack in this director
41824
method
41825
<BR> %ignorestack Class::memberfunction; // do not re-init the stack in
41826
this director method
41827
<BR> %initstack Class; // init the stack on all the
41828
methods of this class
41829
<BR> %initstack; // all director functions will re-init the stack</DIV>
39327
41830
<HR NOSHADE>
39328
41831
<H1><A name="Tcl"></A>31 SWIG and Tcl</H1>
39329
41832
39901
42404
</DIV>
39902
42405
<P> The <TT>%immutable</TT> directive stays in effect until it is
39903
42406
explicitly disabled or cleared using <TT>%mutable</TT>. See the <A href="#SWIG_readonly_variables">
39904
Creatng read-only variables</A> section for further details.</P>
42407
Creating read-only variables</A> section for further details.</P>
39905
42408
<P> If you just want to make a specific variable immutable, supply a
39906
42409
declaration name. For example:</P>
39907
42410
<DIV class="code">
41827
44330
<UL>
41828
44331
<LI><A href="#R_nn2">Bugs</A></LI>
41829
44332
<LI><A href="#R_nn3">Using R and SWIG</A></LI>
41830
<LI><A href="#R_nn4">General policy</A></LI>
41831
<LI><A href="#R_nn5">Language conventions</A></LI>
44333
<LI><A href="#R_nn4">Precompiling large R files</A></LI>
44334
<LI><A href="#R_nn5">General policy</A></LI>
44335
<LI><A href="#R_language_conventions">Language conventions</A></LI>
41832
44336
<LI><A href="#R_nn6">C++ classes</A></LI>
41833
44337
<LI><A href="#R_nn7">Enumerations</A></LI>
41834
44338
</UL>
41836
44340
<!-- INDEX -->
41837
44341
<P> R is a GPL'ed open source statistical and plotting environment.
41838
44342
Information about R can be found at <A href="http://www.r-project.org/">
41839
www.r-project.org</A>. The R binding are under active development and
41840
are extremely experimental. Not all features have been implemented and
41841
the API is not stable.</P>
44343
www.r-project.org</A>. The R bindings are under active development. They
44344
have been used to compile and run an R interface to QuantLib running on
44345
Mandriva Linux with gcc. The R bindings also work on Microsoft Windows
44346
using Visual C++.</P>
41842
44347
<H2><A name="R_nn2"></A>32.1 Bugs</H2>
41843
44348
<P> Currently the following features are not implemented or broken:</P>
41844
44349
<UL>
41845
44350
<LI>Garbage collection of created objects</LI>
41846
44351
<LI>C Array wrappings</LI>
41847
<LI>tested on UNIX only, how well or badly it works on windows is not
41848
known</LI>
41849
44352
</UL>
41850
44353
<H2><A name="R_nn3"></A>32.2 Using R and SWIG</H2>
41851
44354
<P> To use R and SWIG in C mode, execute the following commands where
41852
example_func.c is the name of the file with the functions in them</P>
44355
example.c is the name of the file with the functions in them</P>
41853
44356
<DIV class="shell">
41854
44357
<PRE>
41855
swig -r -o example,c example.i
41856
PKG_LIBS="example_func.c" R CMD SHLIB example.c
44358
swig -r example.i
44359
PKG_LIBS="example.c" R CMD SHLIB example_wrap.c
41857
44360
</PRE>
41858
44361
</DIV>
41859
44362
<P> The corresponding comments for C++ mode are</P>
41860
44363
<DIV class="shell">
41861
44364
<PRE>
41862
swig -c++ -r -o example.cpp example.i
41863
PKG_LIBS="example_func.cxx" R CMD SHLIB example.cpp
44365
swig -c++ -r -o example_wrap.cpp example.i
44366
PKG_LIBS="example.cxx" R CMD SHLIB example_wrap.cpp
41864
44367
</PRE>
41865
44368
</DIV>
41866
44369
<P> Note that R is sensitive to the name of the file and to the file
41867
44370
extension in C and C++ mode. The name of the wrapper file must be the
41868
name of the library. Also in C++ mode, the file extension must be cpp
41869
rather than cxx for the R compile command to recognize it.</P>
41870
<P> The commands produce two files. A dynamic shared object file called
41871
example.so and an R wrapper file called example_wrap.S. To load these
41872
files, start up R and type in the following commands</P>
44371
name of the library. Also in C++ mode, the file extension must be .cpp
44372
rather than .cxx for the R compile command to recognize it.</P>
44373
<P> The commands produces two files. A dynamic shared object file called
44374
example.so, or example.dll, and an R wrapper file called example.R. To
44375
load these files, start up R and type in the following commands</P>
41873
44376
<DIV class="shell">
41874
44377
<PRE>
41875
dyn.load('example.so')
41876
source('example_wrap.S')
44378
dyn.load(paste("example", .Platform$dynlib.ext, sep=""))
44379
source("example.R")
44380
cacheMetaData(1)
41877
44381
</PRE>
41878
</DIV>
44382
</DIV> The cacheMetaData(1) will cause R to refresh its object tables.
44383
Without it, inheritance of wrapped objects may fail.
41879
44384
<P> These two files can be loaded in any order</P>
41880
<H2><A name="R_nn4"></A>32.3 General policy</H2>
44385
<H2><A name="R_nn4"></A>32.3 Precompiling large R files</H2>
44386
In cases where the R file is large, one make save a lot of loading time
44387
by precompiling the R wrapper. This can be done by creating the file
44388
makeRData.R which contains the following
44389
<PRE>
44390
source('BigFile.R')
44391
save(list=ls(all=TRUE),file="BigFile.RData", compress=TRUE)
44392
q(save="no")
44393
</PRE>
44394
This will generate a compiled R file called BigFile.RData that will
44395
save a large amount of loading time.
44396
<H2><A name="R_nn5"></A>32.4 General policy</H2>
41881
44397
<P> The general policy of the module is to treat the C/C++ as a basic
41882
44398
wrapping over the underlying functions and rely on the R type system to
41883
44399
provide R syntax.</P>
41884
<H2><A name="R_nn5"></A>32.4 Language conventions</H2>
44400
<H2><A name="R_language_conventions"></A>32.5 Language conventions</H2>
41885
44401
<P> getitem and setitem use C++ conventions (i.e. zero based indices). [
41886
44402
<!---
41887
44403
and [ are overloaded to allow for R syntax (one based indices and
41888
44404
slices)
41889
44405
</p-->
41890
44406
</P>
41891
<H2><A name="R_nn6"></A>32.5 C++ classes</H2>
44407
<H2><A name="R_nn6"></A>32.6 C++ classes</H2>
41892
44408
<P> C++ objects are implemented as external pointer objects with the
41893
44409
class being the mangled name of the class. The C++ classes are
41894
44410
encapsulated as an SEXP with an external pointer type. The class is the
41895
44411
mangled name of the class. The nice thing about R is that is allows you
41896
44412
to keep track of the pointer object which removes the necessity for a
41897
44413
lot of the proxy class baggage you see in other languages.</P>
41898
<H2><A name="R_nn7"></A>32.6 Enumerations</H2>
44414
<H2><A name="R_nn7"></A>32.7 Enumerations</H2>
41899
44415
<P> enumerations are characters which are then converted back and forth
41900
44416
to ints before calling the C routines. All of the enumeration code is
41901
44417
done in R.</P>
41960
44476
<LI><A href="#Extending_nn43">Documentation</A></LI>
41961
44477
<LI><A href="#Extending_prerequisites">Prerequisites for adding a new
41962
44478
language module to the SWIG distribution</A></LI>
44479
<LI><A href="#Extending_coding_style_guidelines">Coding style guidelines</A>
44480
</LI>
41963
44481
</UL>
41964
44482
</LI>
41965
44483
<LI><A href="#Extending_nn44">Typemaps</A>
42198
44716
known as a "Node". Each node is identified by a symbolic tag.
42199
44717
Furthermore, a node may have an arbitrary number of children. The parse
42200
44718
tree structure and tag names of an interface can be displayed using <TT>
42201
swig -dump_tags</TT>. For example:</P>
44719
swig -debug-tags</TT>. For example:</P>
42202
44720
<DIV class="shell">
42203
44721
<PRE>
42204
$ <B>swig -c++ -python -dump_tags example.i</B>
44722
$ <B>swig -c++ -python -debug-tags example.i</B>
42205
44723
. top (example.i:1)
42206
44724
. top . include (example.i:1)
42207
44725
. top . include . typemap (/r0/beazley/Projects/lib/swig1.3/swig.swg:71)
42253
44771
attribute/value pairs. Internally, the nodes are simply represented by
42254
44772
hash tables. A display of the entire parse-tree structure can be
42255
44773
obtained using <TT>swig -dump_tree</TT>. There are a number of other
42256
parse tree display options, for example, <TT>swig -dump_module</TT>
44774
parse tree display options, for example, <TT>swig -debug-module <n></TT>
42257
44775
will avoid displaying system parse information and only display the
42258
parse tree pertaining to the user's module.</P>
44776
parse tree pertaining to the user's module at stage <TT>n</TT> of
44777
processing.</P>
42259
44778
<DIV class="shell">
42260
44779
<PRE>
42261
$ swig -c++ -python -dump_module example.i
44780
$ swig -c++ -python -debug-module 4 example.i
42262
44781
+++ include ----------------------------------------
42263
44782
| name - "example.i"
42264
44783
42466
44985
void foo(Bar *b);
42467
44986
</PRE>
42468
44987
</DIV>
42469
<P> Now, running SWIG:</P>
44988
<P> There are various <TT>debug-</TT> options that can be useful for
44989
debugging and analysing the parse tree. For example, the <TT>debug-top
44990
<n></TT> or <TT>debug-module <n></TT> options will dump the entire/top
44991
of the parse tree or the module subtree at one of the four <TT>n</TT>
44992
stages of processing. The parse tree can be viewed after the final
44993
stage of processing by running SWIG:</P>
42470
44994
<DIV class="shell">
42471
44995
<PRE>
42472
$ swig -dump_tree example.i
44996
$ swig -debug-top 4 example.i
42473
44997
...
42474
44998
+++ cdecl ----------------------------------------
42475
44999
| sym:name - "foo_i"
42545
45069
simply attaches a new attribute to any parse tree node that matches the
42546
45070
given prototype. When a feature is added, it shows up as an attribute
42547
45071
in the <TT>feature:</TT> namespace. You can see this when running with
42548
the <TT>-dump_tree</TT> option. For example:</P>
45072
the <TT>-debug-top 4</TT> option. For example:</P>
42549
45073
<DIV class="shell">
42550
45074
<PRE>
42551
45075
+++ cdecl ----------------------------------------
44038
46562
which we encourage for all popular languages, there are a few
44039
46563
requirements. While we appreciate that getting all aspects of a new
44040
46564
language working won't happen at the outset, there are a set of minimum
44041
requirements before a module can be committed into the cvs repository
46565
requirements before a module can be committed into the SVN repository
44042
46566
for distribution with future versions of SWIG. The following are really
44043
46567
a summary of this whole section with details being outlined earlier on.</P>
44044
46568
<OL>
44061
46585
test-suite.</LI>
44062
46586
<LI> Provide a chapter in the html documentation on the basics of using
44063
46587
the language module.</LI>
46588
<LI> Ensure your source code is formatted according to the <A href="#Extending_coding_style_guidelines">
46589
coding style guidelines</A>.</LI>
44064
46590
<LI> Finally, email the SWIG developers with a patch and a demonstration
44065
46591
of commitment to maintaining the language module, certainly in the
44066
46592
short term and ideally long term.</LI>
44067
46593
</OL>
44068
<P> Once accepted into CVS, development efforts should concentrate on
46594
<P> Once accepted into SVN, development efforts should concentrate on
44069
46595
getting the entire test-suite to work with plenty of runtime tests.
44070
46596
Runtime tests should be for existing testcases and new test cases
44071
46597
should be added should there be an area not already covered by the
44072
46598
existing tests.</P>
46599
<H3><A name="Extending_coding_style_guidelines"></A>33.10.14 Coding
46600
style guidelines</H3>
46601
<P> The coding guidelines for the C/C++ source code are pretty much K&R
46602
C style. The style can be inferred from the existing code base and is
46603
largely dictated by the <TT>indent</TT> code beautifier tool set to K&R
46604
style. The code can formatted using the make targets in the Source
46605
directory. Below is an example of how to format the emit.cxx file:</P>
46606
<BLOCKQUOTE>
46607
<PRE>
46608
$ cd Source
46609
$ make beautify-file INDENTFILE=Modules/emit.cxx
46610
</PRE>
46611
</BLOCKQUOTE>
46612
<P> Of particular note is indentation is set to 2 spaces and a tab is
46613
used instead of 8 spaces. The generated C/C++ code should also follow
46614
this style as close as possible. However, tabs should be avoided as
46615
unlike the SWIG developers, users will never have consistent tab
46616
settings.</P>
44073
46617
<H2><A name="Extending_nn44"></A>33.11 Typemaps</H2>
44074
46618
<H3><A name="Extending_nn45"></A>33.11.1 Proxy classes</H3>
44075
46619
<H2><A name="Extending_nn46"></A>33.12 Guide to parse tree nodes</H2>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1