/trunk/Doc/Manual/Allegrocl.html
HTML | 2027 lines | 1671 code | 353 blank | 3 comment | 0 complexity | 886f5a6988c8b604cbf992f7f8fbfa1f MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<!-- Hand-written HTML --> 3<html> 4<head> 5<title>SWIG and Allegro Common Lisp</title> 6<link rel="stylesheet" type="text/css" href="style.css"> 7</head> 8 9<body bgcolor="#ffffff"> 10 11<H1><a name="Allegrocl"></a>17 SWIG and Allegro Common Lisp</H1> 12<!-- INDEX --> 13<div class="sectiontoc"> 14<ul> 15<li><a href="#Allegrocl_nn2">Basics</a> 16<ul> 17<li><a href="#Allegrocl_nn3">Running SWIG</a> 18<li><a href="#Allegrocl_nn4">Command Line Options</a> 19<li><a href="#Allegrocl_nn5">Inserting user code into generated files</a> 20</ul> 21<li><a href="#Allegrocl_nn6">Wrapping Overview</a> 22<ul> 23<li><a href="#Allegrocl_nn7">Function Wrapping</a> 24<li><a href="#Allegrocl_nn8">Foreign Wrappers</a> 25<li><a href="#Allegrocl_nn9">FFI Wrappers</a> 26<li><a href="#Allegrocl_nn10">Non-overloaded Defuns</a> 27<li><a href="#Allegrocl_nn11">Overloaded Defuns</a> 28<li><a href="#Allegrocl_nn12">What about constant and variable access?</a> 29<li><a href="#Allegrocl_nn13">Object Wrapping</a> 30</ul> 31<li><a href="#Allegrocl_nn14">Wrapping Details</a> 32<ul> 33<li><a href="#Allegrocl_nn15">Namespaces</a> 34<li><a href="#Allegrocl_nn16">Constants</a> 35<li><a href="#Allegrocl_nn17">Variables</a> 36<li><a href="#Allegrocl_nn18">Enumerations</a> 37<li><a href="#Allegrocl_nn19">Arrays</a> 38<li><a href="#Allegrocl_nn20">Classes and Structs and Unions (oh my!)</a> 39<ul> 40<li><a href="#Allegrocl_nn21">CLOS wrapping of</a> 41<li><a href="#Allegrocl_nn22">CLOS Inheritance</a> 42<li><a href="#Allegrocl_nn23">Member fields and functions</a> 43<li><a href="#Allegrocl_nn24">Why not directly access C++ classes using foreign types?</a> 44</ul> 45<li><a href="#Allegrocl_nn25">Templates</a> 46<ul> 47<li><a href="#Allegrocl_nn26">Generating wrapper code for templates</a> 48<li><a href="#Allegrocl_nn27">Implicit Template instantiation</a> 49</ul> 50<li><a href="#Allegrocl_nn28">Typedef, Templates, and Synonym Types</a> 51<ul> 52<li><a href="#Allegrocl_nn29">Choosing a primary type</a> 53</ul> 54<li><a href="#Allegrocl_nn30">Function overloading/Parameter defaulting</a> 55<li><a href="#Allegrocl_nn31">Operator wrapping and Operator overloading</a> 56<li><a href="#Allegrocl_nn32">Varargs</a> 57<li><a href="#Allegrocl_nn33">C++ Exceptions</a> 58<li><a href="#Allegrocl_nn34">Pass by value, pass by reference</a> 59</ul> 60<li><a href="#Allegrocl_nn35">Typemaps</a> 61<ul> 62<li><a href="#Allegrocl_nn36">Code Generation in the C++ Wrapper</a> 63<ul> 64<li><a href="#Allegrocl_nn37">IN Typemap</a> 65<li><a href="#Allegrocl_nn38">OUT Typemap</a> 66<li><a href="#Allegrocl_nn39">CTYPE Typemap</a> 67</ul> 68<li><a href="#Allegrocl_nn40">Code generation in Lisp wrappers</a> 69<ul> 70<li><a href="#Allegrocl_nn41">LIN Typemap</a> 71<li><a href="#Allegrocl_nn42">LOUT Typemap</a> 72<li><a href="#Allegrocl_nn43">FFITYPE Typemap</a> 73<li><a href="#Allegrocl_nn44">LISPTYPE Typemap</a> 74<li><a href="#Allegrocl_nn45">LISPCLASS Typemap</a> 75</ul> 76<li><a href="#Allegrocl_nn46">Modifying SWIG behavior using typemaps</a> 77</ul> 78<li><a href="#Allegrocl_nn47">Identifier Converter functions</a> 79<ul> 80<li><a href="#Allegrocl_nn48">Creating symbols in the lisp environment</a> 81<li><a href="#Allegrocl_nn49">Existing identifier-converter functions</a> 82<ul> 83<li><a href="#Allegrocl_nn50">identifier-convert-null</a> 84<li><a href="#Allegrocl_nn51">identifier-convert-lispify</a> 85<li><a href="#Allegrocl_nn52">Default identifier to symbol conversions</a> 86</ul> 87<li><a href="#Allegrocl_nn53">Defining your own identifier-converter</a> 88<li><a href="#Allegrocl_nn54">Instructing SWIG to use a particular identifier-converter</a> 89</ul> 90</ul> 91</div> 92<!-- INDEX --> 93 94 95 96<p> 97This chapter describes SWIG's support of Allegro Common Lisp. Allegro 98CL is a full-featured implementation of the Common Lisp language 99standard that includes many vendor-specific enhancements and add-on 100modules for increased usability. 101</p> 102 103<p> 104One such module included in Allegro CL is the Foreign Functions 105Interface (FFI). This module, tailored primarily toward interfacing 106with C/C++ and, historically, Fortran, provides a means by which 107compiled foreign code can be loaded into a running lisp 108environment and executed. The interface supports the calling of 109foreign functions and methods, allows for executing lisp routines 110from foreign code (callbacks), and the passing of data between foreign 111and lisp code. 112</p> 113 114<p> 115The goal of this module is to make it possible to quickly generate the 116necessary foreign function definitions so one can make use of C/C++ 117foreign libraries directly from lisp without the tedium of having to 118code them by hand. When necessary, it will also generate further C/C++ 119code that will need to be linked with the intended library for proper 120interfacing from lisp. It has been designed with an eye toward 121flexibility. Some foreign function calls may release the heap, while 122other should not. Some foreign functions should automatically convert 123lisp strings into native strings, while others should not. These 124adjustments and many more are possible with the current module. 125</p> 126 127<p> 128It is significant to note that, while this is a vendor-specific 129module, we would like to acknowledge the current and ongoing 130work by developers in the open source lisp community that are 131working on similar interfaces to implementation-independent 132foreign function interfaces (UFFI or CFFI, for example). Such 133work can only benefit the lisp community, and we would not 134be unhappy to see some enterprising folk use this work to add 135to it. 136</p> 137 138<H2><a name="Allegrocl_nn2"></a>17.1 Basics</H2> 139 140 141<H3><a name="Allegrocl_nn3"></a>17.1.1 Running SWIG</H3> 142 143 144<p> 145If you're reading this, you must have some library you need to 146generate an interface for. In order for SWIG to do this work, however, 147it needs a bit of information about how it should go about creating 148your interface, and what you are interfacing to. 149</p> 150 151<p> 152SWIG expects a description of what in the foreign interface you wish 153to connect to. It must consisting of C/C++ declarations and special 154SWIG directives. SWIG can be furnished with a header file, but an 155interface can also be generated without library headers by supplying a 156simple text file--called the interface file, which is typically named 157with a <tt>.i</tt> extension--containing any foreign declarations of 158identifiers you wish to use. The most common approach is to use a an 159interface file with directives to parse the needed headers. A straight 160parse of library headers will result in usable code, but SWIG 161directives provides much freedom in how a user might tailor the 162generated code to their needs or style of coding. 163</p> 164 165<p> 166Note that SWIG does not require any function definitions; the 167declarations of those functions is all that is necessary. Be careful 168when tuning the interface as it is quite possible to generate code 169that will not load or compile. 170</p> 171 172<p> 173An example interface file is shown below. It makes use of two SWIG 174directives, one of which requests that the declarations in a header 175file be used to generate part of the interface, and also includes an 176additional declaration to be added.</p> 177 178<div class="code">example.i 179<pre> 180%module example 181 182%include "header.h" 183 184int fact(int n); 185</pre> 186</div> 187 188<p>The contents of header.h are very simple:</p> 189<div class="code">header.h 190<pre> 191int fact(char *statement); // pass it a fact, and it will rate it. 192</pre> 193</div> 194 195<p>The contents of example.cl will look like this:</p> 196 197<div class="targetlang">example.cl 198<pre> 199(defpackage :example 200 (:use :common-lisp :swig :ff :excl)) 201 202 ... helper routines for defining the interface ... 203 204(swig-in-package ()) 205 206(swig-defun ("fact") 207 ((PARM0_statement cl:string (* :char) )) 208 (:returning (:int ) 209 :strings-convert t) 210 (let ((SWIG_arg0 PARM0_statement)) 211 (swig-ff-call SWIG_arg0))) 212 213(swig-defun ("fact") 214 ((PARM0_n cl:integer :int )) 215 (:returning (:int ) 216 :strings-convert t) 217 (let ((SWIG_arg0 PARM0_n)) 218 (swig-ff-call SWIG_arg0))) 219 220(swig-dispatcher ("fact" :type :function :arities (1))) 221</pre> 222</div> 223 224<p> 225The generated file contains calls to internal swig helper 226functions. In this case there are two calls to swig-defun. 227These calls will expand into code that will make the appropriate 228definitions using the Allegro FFI. Note also, that this code is 229<b>erroneous</b>. Function overloading is not supported in C, and this 230code will not compile even though SWIG did not complain. 231</p> 232 233<p> 234In order to generate a C interface to Allegro CL using this code run 235swig using the <tt>-allegrocl</tt> option, as below: 236</p> 237 238<div class="shell"> 239<pre> 240% swig -allegrocl example.i 241</pre> 242</div> 243 244<p> 245When building an interface to C++ code, include the <tt>-c++</tt> option: 246</p> 247 248<div class="shell"> 249<pre> 250% swig -allegrocl -c++ example.i 251</pre> 252</div> 253 254<p> 255As a result of running one of the above commands, a file named <tt>example.cl</tt> 256will be generated containing the lisp side of the interface. As well, a file 257<tt>example_wrap.cxx</tt> is also generated, containing C/C++ wrapper code to 258facilitate access to C++ methods, enumeration values, and constant values. 259Wrapper functions are necessary in C++ due to the lack of a standard for mangling 260the names of symbols across all C++ compilers. These wrapper functions are 261exported from the shared library as appropriate, using the C name mangling 262convention. The lisp code that is generated will interface to your foreign 263library through these wrappers. 264</p> 265 266<p> 267It is possible to disable the creation of the .cxx file when generating a C 268interface by using the -nocwrap command-line argument. For interfaces that 269don't contain complex enum or constant expressions, contain nested struct/union 270declarations, or doesn't need to use many of the SWIG customization featuers, 271this will result in a more streamlined, direct interface to the 272intended module. 273</p> 274 275<p> 276The generated wrapper file is below. It contains very simple 277wrappers by default, that simply pass the arguments to the 278actual function. 279</p> 280 281<div class="code">example_wrap.i 282<pre> 283 ... lots of SWIG internals ... 284 285EXPORT int ACL___fact__SWIG_0 (char *larg1) { 286 int lresult = (int)0 ; 287 char *arg1 = (char *) 0 ; 288 int result; 289 290 arg1 = larg1; 291 try { 292 result = (int)fact(arg1); 293 294 lresult = result; 295 return lresult; 296 } catch (...) { 297 return (int)0; 298 } 299} 300 301 302EXPORT int ACL___fact__SWIG_1 (int larg1) { 303 int lresult = (int)0 ; 304 int arg1 ; 305 int result; 306 307 arg1 = larg1; 308 try { 309 result = (int)fact(arg1); 310 311 lresult = result; 312 return lresult; 313 } catch (...) { 314 return (int)0; 315 } 316} 317</pre> 318</div> 319 320<p> 321And again, the generated lisp code. Note that it differs from 322what is generated when parsing C code: 323</p> 324 325<div class="targetlang"> 326<pre> 327 ... 328 329(swig-in-package ()) 330 331(swig-defmethod ("fact" "ACL___fact__SWIG_0" :type :function :arity 1) 332 ((PARM0_statement cl:string (* :char) )) 333 (:returning (:int ) 334 :strings-convert t) 335 (let ((SWIG_arg0 PARM0_statement)) 336 (swig-ff-call SWIG_arg0))) 337 338(swig-defmethod ("fact" "ACL___fact__SWIG_1" :type :function :arity 1) 339 ((PARM0_n cl:integer :int )) 340 (:returning (:int ) 341 :strings-convert t) 342 (let ((SWIG_arg0 PARM0_n)) 343 (swig-ff-call SWIG_arg0))) 344 345(swig-dispatcher ("fact" :type :function :arities (1))) 346</pre> 347</div> 348 349<p>In this case, the interface generates two swig-defmethod forms and 350a swig-dispatcher form. This provides a single functional interface for 351all overloaded routines. A more detailed description of this features 352is to be found in the section titled <b>Function overloading/Parameter defaulting</b>. 353 354<p> 355In order to load a C++ interface, you will need to build a shared library 356from example_wrap.cxx. Be sure to link in the actual library you created 357the interface for, as well as any other dependent shared libraries. For 358example, if you intend to be able to call back into lisp, you will also 359need to link in the Allegro shared library. The library you create from 360the C++ wrapper will be what you then load into Allegro CL. 361</p> 362 363<H3><a name="Allegrocl_nn4"></a>17.1.2 Command Line Options</H3> 364 365 366<p> 367There are three Allegro CL specific command-line option: 368</p> 369 370<div class="shell"> 371<pre> 372swig -allegrocl [ options ] filename 373 374 -identifier-converter [name] - Binds the variable swig:*swig-identifier-convert* 375 in the generated .cl file to <tt>name</tt>. 376 This function is used to generate symbols 377 for the lisp side of the interface. 378 379 -cwrap - [default] Generate a .cxx file containing C wrapper function when 380 wrapping C code. The interface generated is similar to what is 381 done for C++ code. 382 -nocwrap - Explicitly turn off generation of .cxx wrappers for C code. Reasonable 383 for modules with simple interfaces. Can not handle all legal enum 384 and constant constructs, or take advantage of SWIG customization features. 385 386 -isolate - With this command-line argument, all lisp helper functions are defined 387 in a unique package named <tt>swig.<module-name></tt> rather than 388 <tt>swig</tt>. This prevents conflicts when the module is 389 intended to be used with other swig generated interfaces that may, 390 for instance, make use of different identifier converters. 391</pre> 392</div> 393 394<p> 395See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter 396functions</a> for more details. 397</p> 398 399<H3><a name="Allegrocl_nn5"></a>17.1.3 Inserting user code into generated files</H3> 400 401 402<p> 403It is often necessary to include user-defined code into the 404automatically generated interface files. For example, when building 405a C++ interface, example_wrap.cxx will likely not compile unless 406you add a <tt>#include "header.h"</tt> directive. This can be done 407using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive: 408</p> 409 410<div class="code"> 411<pre> 412%module example 413 414%{ 415#include "header.h" 416%} 417 418%include "header.h" 419 420int fact(int n); 421</pre> 422</div> 423 424<p> 425Additional sections have been added for inserting into the 426generated lisp interface file 427</p> 428<ul> 429 <li><tt>lisphead</tt> - inserts before type declarations</li> 430 <li><tt>lisp</tt> - inserts after type declarations according to 431 where it appears in the .i file</li> 432</ul> 433<p> 434Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for 435<tt>%insert("header") %{ ... %}</tt>. 436</p> 437 438 439<H2><a name="Allegrocl_nn6"></a>17.2 Wrapping Overview</H2> 440 441 442<p> 443New users to SWIG are encouraged to read 444<a href="SWIG.html#SWIG">SWIG Basics</a>, and 445<a href="SWIGPlus.html#SWIGPlus">SWIG and C++</a>, for those 446interested in generating an interface to C++. 447</p> 448 449<H3><a name="Allegrocl_nn7"></a>17.2.1 Function Wrapping</H3> 450 451 452 <p> 453 Writing lisp code that directly invokes functions at the foreign 454 function interface level can be cumbersome. Data must often be 455 translated between lisp and foreign types, data extracted from 456 objects, foreign objects allocated and freed upon completion of 457 the foreign call. Dealing with pointers can be unwieldy when it 458 comes to keeping them distinct from other valid integer values. 459 </p> 460 461 <p> 462 We make an attempt to ease some of these burdens by making the 463 interface to foreign code much more lisp-like, rather than C 464 like. How this is done is described in later chapters. The 465 layers themselves, appear as follows: 466 </p> 467 468 <div class="diagram"> 469 <pre> 470 ______________ 471 | | (foreign side) 472 | Foreign Code | What we're generating an interface to. 473 |______________| 474 | 475 | 476 _______v______ 477 | | (foreign side) 478 | Wrapper code | extern "C" wrappers calling C++ 479 |______________| functions and methods. 480 | 481 . . . - - + - - . . . 482 _______v______ 483 | | (lisp side) 484 | FFI Layer | Low level lisp interface. ff:def-foreign-call, 485 |______________| ff:def-foreign-variable 486 | 487 +---------------------------- 488 _______v______ _______v______ 489 | | | | (lisp side) 490 | Defuns | | Defmethods | wrapper for overloaded 491 |______________| |______________| functions or those with 492 (lisp side) | defaulted arguments 493 Wrapper for non-overloaded | 494 functions and methods _______v______ 495 | | (lisp side) 496 | Defuns | dispatch function 497 |______________| to overloads based 498 on arity 499 </pre> 500 </div> 501 502<H3><a name="Allegrocl_nn8"></a>17.2.2 Foreign Wrappers</H3> 503 504 505 <p> 506 These wrappers are as generated by SWIG default. The types of 507 function parameters can be transformed in place using the CTYPE 508 typemap. This is use for converting pass-by-value parameters to 509 pass-by-reference where necessary. All wrapper parameters are then 510 bound to local variables for possible transformation of values 511 (see LIN typemap). Return values can be transformed via the OUT 512 typemap. 513 </p> 514 515<H3><a name="Allegrocl_nn9"></a>17.2.3 FFI Wrappers</H3> 516 517 518 <p> 519 These are the generated ff:def-foreign-call forms. No typemaps are 520 applicable to this layer, but the <tt>%ffargs</tt> directive is 521 available for use in .i files, to specify which keyword arguments 522 should be specified for a given function. 523 </p> 524 525 <div class="code">ffargs.i: 526 <pre> 527%module ffargs 528 529%ffargs(strings_convert="nil",call_direct="t") foo; 530%ffargs(strings_convert="nil",release_heap=":never",optimize_for_space="t") bar; 531 532int foo(float f1, float f2); 533int foo(float f1, char c2); 534 535void bar(void *lisp_fn); 536 537char *xxx(); 538 </pre> 539 </div> 540 541 <p>Generates: 542 </p> 543 <div class="targetlang">ffargs.cl: 544 <pre> 545(swig-in-package ()) 546 547(swig-defmethod ("foo" "ACL___foo__SWIG_0" :type :function :arity 2) 548 ((PARM0_f1 cl:single-float :float ) 549 (PARM1_f2 cl:single-float :float )) 550 (:returning (:int ) 551 :call-direct t 552 :strings-convert nil) 553 (let ((SWIG_arg0 PARM0_f1)) 554 (let ((SWIG_arg1 PARM1_f2)) 555 (swig-ff-call SWIG_arg0 SWIG_arg1)))) 556 557(swig-defmethod ("foo" "ACL___foo__SWIG_1" :type :function :arity 2) 558 ((PARM0_f1 cl:single-float :float ) 559 (PARM1_c2 cl:character :char character)) 560 (:returning (:int ) 561 :call-direct t 562 :strings-convert nil) 563 (let ((SWIG_arg0 PARM0_f1)) 564 (let ((SWIG_arg1 PARM1_c2)) 565 (swig-ff-call SWIG_arg0 SWIG_arg1)))) 566 567(swig-dispatcher ("foo" :type :function :arities (2))) 568(swig-defun ("bar" "ACL___bar__SWIG_0" :type :function) 569 ((PARM0_lisp_fn (* :void) )) 570 (:returning (:void ) 571 :release-heap :never 572 :optimize-for-space t 573 :strings-convert nil) 574 (let ((SWIG_arg0 PARM0_lisp_fn)) 575 (swig-ff-call SWIG_arg0))) 576 577 578(swig-defun ("xxx" "ACL___xxx__SWIG_0" :type :function) 579 (:void) 580 (:returning ((* :char) ) 581 :strings-convert t) 582 (swig-ff-call)) 583 </pre> 584 </div> 585 586 <div class="code"> 587 <pre>%ffargs(strings_convert="t");</pre> 588 </div> 589 590 <p> 591 Is the only default value specified in <tt>allegrocl.swg</tt> to force 592 the muffling of warnings about automatic string conversion when defining 593 ff:def-foreign-call's. 594 </p> 595 596<H3><a name="Allegrocl_nn10"></a>17.2.4 Non-overloaded Defuns</H3> 597 598 599 <p> 600 These are simple defuns. There is no typechecking of arguments. 601 Parameters are bound to local variables for possible 602 transformation of values, such as pulling values out of instance 603 slots or allocating temporary stack allocated structures, via the 604 <tt>lin</tt> typemap. These arguments are then passed to the 605 foreign-call (where typechecking may occur). The return value from 606 this function can be manipulated via the <tt>lout</tt> typemap. 607 </p> 608 609<H3><a name="Allegrocl_nn11"></a>17.2.5 Overloaded Defuns</H3> 610 611 612 <p> 613 In the case of overloaded functions, mulitple layers are 614 generated. First, all the overloads for a given name are separated 615 out into groups based on arity, and are wrapped in 616 defmethods. Each method calls a distinct wrapper function, but are 617 themselves distinguished by the types of their arguments 618 (see <tt>lispclass</tt> typemap). These are further wrapped in a 619 dispatching function (defun) which will invoke the appropriate 620 generic-function based on arity. This provides a single functional 621 interface to all overloads. The return value from this function 622 can be manipulated via the <tt>lout</tt> typemap. 623 </p> 624 625<H3><a name="Allegrocl_nn12"></a>17.2.6 What about constant and variable access?</H3> 626 627 628 <p> 629 Along with the described functional layering, when creating a .cxx wrapper, 630 this module will generate getter and--if not immutable--setter, 631 functions for variables and constants. If the -nocwrap option is used, 632 <tt>defconstant</tt> and <tt>ff:def-foreign-variable</tt> forms will be 633 generated for accessing constants and global variables. These, along with 634 the <tt>defuns</tt> listed above are the intended API for calling 635 into the foreign module. 636 </p> 637 638<H3><a name="Allegrocl_nn13"></a>17.2.7 Object Wrapping</H3> 639 640 641 <p> 642 All non-primitive types (Classes, structs, unions, and typedefs 643 involving same) have a corresponding foreign-type defined on the 644 lisp side via ff:def-foreign-type. 645 </p> 646 647 <p> 648 All non-primitive types are further represented by a CLOS class, 649 created via defclass. An attempt is made to create the same class 650 hierarchy, with all classes inheriting directly or indirectly from 651 ff:foreign-pointer. Further, wherever it is apparent, all pointers 652 returned from foreign code are wrapped in a CLOS instance of the 653 appropriate class. For ff:def-foreign-calls that have been defined 654 to expect a :foreign-address type as argument, these CLOS instances 655 can legally be passed and the pointer to the C++ object 656 automatically extracted. This is a natural feature of Allegro's 657 foreign function interface. 658 </p> 659 660<H2><a name="Allegrocl_nn14"></a>17.3 Wrapping Details</H2> 661 662 663 <p> 664 In this section is described how particular C/C++ constructs are 665 translated into lisp. 666 </p> 667 668<H3><a name="Allegrocl_nn15"></a>17.3.1 Namespaces</H3> 669 670 671 <p> 672 C++ namespaces are translated into Lisp packages by SWIG. The 673 Global namespace is mapped to a package named by the <tt>%module</tt> 674 directive or the <tt>-module</tt> command-line argument. Further 675 namespaces are generated by the <tt>swig-defpackage</tt> utility 676 function and given names based on Allegro CLs nested namespace 677 convention. For example: 678 </p> 679 680 <div class="code">foo.i: 681 <pre> 682%module foo 683 684%{ 685#include "foo.h" 686%} 687 688%include "foo.h" 689 690namespace car { 691 ... 692 namespace tires { 693 int do_something(int n); 694 } 695} 696 </pre> 697 </div> 698 <p>Generates the following code. 699 </p> 700 <div class="targetlang">foo.cl 701 <pre> 702(defpackage :foo 703 (:use :common-lisp :swig :ff :excl)) 704 705... 706 707(swig-defpackage ("car")) 708(swig-defpackage ("car" "tires")) 709 710... 711 712(swig-in-package ("car" "tires")) 713(swig-defun ("do_something" "ACL_car_tires__do_something__SWIG_0" :type :function) 714 ((PARM0_n :int )) 715 (:returning (:int ) 716 :strings-convert t) 717 (let ((SWIG_arg0 PARM0_n)) 718 (swig-ff-call SWIG_arg0))) 719 </pre> 720 </div> 721 722 <p> 723 The above interface file would cause packages foo, foo.car, and 724 foo.car.tires to be created. One would find the function wrapper 725 for do_something defined in the foo.car.tires package(*). 726 </p> 727 728 <p>(<b>*</b>) Except for the package named by the module, all 729 namespace names are passed to the identifier-converter-function 730 as strings with a <tt>:type</tt> of <tt>:namespace</tt>. It is the 731 job of this function to generate the desired symbol, accounting for 732 case preferences, additional naming cues, etc. 733 </p> 734 735 <p> 736 Note that packages created by <tt>swig-defpackage</tt> do not 737 use the COMMON-LISP or EXCL package. This reduces possible 738 conflicts when defining foreign types via the SWIG interface 739 in <b>all but the toplevel modules package</b>. This may 740 lead to confusion if, for example, the current package is 741 <tt>foo.car.tires</tt> and you attempt to use a common-lisp 742 function such as <tt>(car '(1 2 3)</tt>. 743 </p> 744 745<H3><a name="Allegrocl_nn16"></a>17.3.2 Constants</H3> 746 747 748 749 <p> 750 Constants, as declared by the preprocessor #define macro or SWIG 751 <tt>%constant</tt> directive, are included in SWIGs parse tree 752 when it can be determined that they are, or could be reduced to, 753 a literal value. Such values are translated into defconstant 754 forms in the generated lisp wrapper when the -nocwrap command-line 755 options is used. Else, wrapper functions are generated as in the 756 case of variable access (see section below). 757 </p> 758 <p> 759 Here are examples of simple preprocessor constants when using -nocwrap. 760 </p> 761 <div class="code"> 762 <pre> 763#define A 1 => (swig-defconstant "A" 1) 764#define B 'c' => (swig-defconstant "B" #\c) 765#define C B => (swig-defconstant "C" #\c) 766#define D 1.0e2 => (swig-defconstant "D" 1.0d2) 767#define E 2222 => (swig-defconstant "E" 2222) 768#define F (unsigned int)2222 => no code generated 769#define G 1.02e2f => (swig-defconstant "G" 1.02f2) 770#define H foo => no code generated 771 </pre> 772 </div> 773 774 <p> 775 Note that where SWIG is unable to determine if a constant is 776 a literal, no node is added to the SWIG parse tree, and so 777 no values can be generated. 778 </p> 779 780 <p> 781 For preprocessor constants containing expressions which can be 782 reduced to literal values, nodes are created, but with no simplification 783 of the constant value. A very very simple infix to prefix converter 784 has been implemented that tries to do the right thing for simple cases, but 785 does not for more complex expressions. If the literal parser determines 786 that something is wrong, a warning will be generated and the literal 787 expression will be included in the generated code, but commented out. 788 </p> 789 790 <div class="code"> 791 <pre> 792#define I A + E => (swig-defconstant "I" (+ 1 2222)) 793#define J 1|2 => (swig-defconstant "J" (logior 1 2)) 794#define Y 1 + 2 * 3 + 4 => (swig-defconstant "Y" (* (+ 1 2) (+ 3 4))) 795#define Y1 (1 + 2) * (3 + 4) => (swig-defconstant "Y1" (* (+ 1 2) (+ 3 4))) 796#define Y2 1 * 2 + 3 * 4 => (swig-defconstant "Y2" (* 1 (+ 2 3) 4)) ;; WRONG 797#define Y3 (1 * 2) + (3 * 4) => (swig-defconstant "Y3" (* 1 (+ 2 3) 4)) ;; WRONG 798#define Z 1 + 2 - 3 + 4 * 5 => (swig-defconstant "Z" (* (+ 1 (- 2 3) 4) 5)) ;; WRONG 799 </pre> 800 </div> 801 <p> 802 Users are cautioned to get to know their constants before use, or 803 not use the <tt>-nocwrap</tt> command-line option. 804 </p> 805 806<H3><a name="Allegrocl_nn17"></a>17.3.3 Variables</H3> 807 808 809 <p> 810 For C wrapping, a def-foreign-variable call is generated for access 811 to global variables. 812 </p> 813 <p> 814 When wrapping C++ code, both global and member variables, getter 815 wrappers are generated for accessing their value, and if not immutable, 816 setter wrappers as well. In the example below, note the lack of a 817 setter wrapper for global_var, defined as const. 818 </p> 819 820 <div class="code">vars.h 821 <pre> 822namespace nnn { 823 int const global_var = 2; 824 float glob_float = 2.0; 825} 826 </pre> 827 </div> 828 829 <p> 830 Generated code: 831 </p> 832 <div class="targetlang">vars.cl 833 <pre> 834(swig-in-package ("nnn")) 835(swig-defun ("global_var" "ACL_nnn__global_var_get__SWIG_0" :type :getter) 836 (:void) 837 (:returning (:int ) 838 :strings-convert t) 839 (swig-ff-call)) 840 841 842(swig-defun ("glob_float" "ACL_nnn__glob_float_set__SWIG_0" :type :setter) 843 ((PARM0_glob_float :float )) 844 (:returning (:void ) 845 :strings-convert t) 846 (let ((SWIG_arg0 PARM0_glob_float)) 847 (swig-ff-call SWIG_arg0))) 848 849 850(swig-defun ("glob_float" "ACL_nnn__glob_float_get__SWIG_0" :type :getter) 851 (:void) 852 (:returning (:float ) 853 :strings-convert t) 854 (swig-ff-call)) 855 </pre> 856 </div> 857 858 <p> 859 Note also, that where applicable, setter wrappers are implemented 860 as setf methods on the getter function, providing a lispy interface 861 to the foreign code. 862 </p> 863 864 <div class="targetlang"> 865 <pre> 866user> (load "globalvar.dll") 867; Foreign loading globalvar.dll. 868t 869user> (load "globalvar.cl") 870; Loading c:\mikel\src\swig\test\globalvar.cl 871t 872user> 873globalvar> (globalvar.nnn::global_var) 8742 875globalvar> (globalvar.nnn::glob_float) 8762.0 877globalvar> (setf (globalvar.nnn::glob_float) 3.0) 8783.0 879globalvar> (globalvar.nnn::glob_float) 8803.0 881 </pre> 882 </div> 883 884<H3><a name="Allegrocl_nn18"></a>17.3.4 Enumerations</H3> 885 886 887 <p> 888 In C, an enumeration value is an integer value, while in C++ an 889 enumeration value is implicitly convertible to an integer value, 890 but can also be distinguished by it's enum type. For each enum 891 declaration a def-foreign-type is generated, assigning the enum 892 a default type of :int. Users may adjust the foreign type of 893 enums via SWIG <tt>typemaps</tt>. 894 </p> 895 896 <p> 897 Enum values are a bit trickier as they can be initialized using 898 any valid C/C++ expression. In C with the -nocwrap command-line option, 899 we handle the typical cases (simple integer initialization) and 900 generate a defconstant form for each enum value. This has the advantage 901 of it not being necessary to probe into foreign space to retrieve enum 902 values. When generating a .cxx wrapper file, a more general solution is 903 employed. A wrapper variable is created in the module_wrap.cxx file, and 904 a ff:def-foreign-variable call is generated to retrieve it's value into lisp. 905 </p> 906 907 <p>For example, the following header file 908 <div class="code">enum.h: 909 <pre> 910enum COL { RED, GREEN, BLUE }; 911enum FOO { FOO1 = 10, FOO2, FOO3 }; 912 </pre> 913 </div> 914 <p> 915 In -nocwrap mode, generates 916 </p> 917 <div class="targetlang">enum.cl: 918 <pre> 919(swig-def-foreign-type "COL" :int) 920(swig-defconstant "RED" 0) 921(swig-defconstant "GREEN" (+ #.(swig-insert-id "RED" () :type :constant) 1)) 922(swig-defconstant "BLUE" (+ #.(swig-insert-id "GREEN" () :type :constant) 1)) 923 924(swig-def-foreign-type "FOO" :int) 925(swig-defconstant "FOO1" 10) 926(swig-defconstant "FOO2" (+ #.(swig-insert-id "FOO1" () :type :constant) 1)) 927(swig-defconstant "FOO3" (+ #.(swig-insert-id "FOO2" () :type :constant) 1)) 928 </pre> 929 </div> 930 931 <p>And when generating a .cxx wrapper 932 <div class="code">enum_wrap.cxx: 933 <pre> 934EXPORT const int ACL_ENUM___RED__SWIG_0 = RED; 935EXPORT const int ACL_ENUM___GREEN__SWIG_0 = GREEN; 936EXPORT const int ACL_ENUM___BLUE__SWIG_0 = BLUE; 937EXPORT const int ACL_ENUM___FOO1__SWIG_0 = FOO1; 938EXPORT const int ACL_ENUM___FOO2__SWIG_0 = FOO2; 939EXPORT const int ACL_ENUM___FOO3__SWIG_0 = FOO3; 940 </pre> 941 </div> 942 <p> 943 and 944 </p> 945 <div class="targetlang">enum.cl: 946 <pre> 947(swig-def-foreign-type "COL" :int) 948(swig-defvar "RED" "ACL_ENUM___RED__SWIG_0" :type :constant) 949(swig-defvar "GREEN" "ACL_ENUM___GREEN__SWIG_0" :type :constant) 950(swig-defvar "BLUE" "ACL_ENUM___BLUE__SWIG_0" :type :constant) 951 952(swig-def-foreign-type "FOO" :int) 953(swig-defvar "FOO1" "ACL_ENUM___FOO1__SWIG_0" :type :constant) 954(swig-defvar "FOO2" "ACL_ENUM___FOO2__SWIG_0" :type :constant) 955(swig-defvar "FOO3" "ACL_ENUM___FOO3__SWIG_0" :type :constant) 956 957 </pre> 958 </div> 959 960<H3><a name="Allegrocl_nn19"></a>17.3.5 Arrays</H3> 961 962 963 <p> 964 One limitation in the Allegro CL foreign-types module, is that, 965 without macrology, expressions may not be used to specify the 966 dimensions of an array declaration. This is not a horrible 967 drawback unless it is necessary to allocate foreign structures 968 based on the array declaration using ff:allocate-fobject. When it 969 can be determined that an array bound is a valid numeric value, 970 SWIG will include this in the generated array declaration on the 971 lisp side, otherwise the value will be included, but commented out. 972 </p> 973 974 <p> 975 Below is a comprehensive example, showing a number of legal 976 C/C++ array declarations and how they are translated 977 into foreign-type specifications in the generated lisp code. 978 </p> 979 <div class="code">array.h 980 <pre> 981#define MAX_BUF_SIZE 1024 982 983namespace FOO { 984 int global_var1[13]; 985 float global_var2[MAX_BUF_SIZE]; 986 987} 988 989enum COLOR { RED = 10, GREEN = 20, BLUE, PURPLE = 50, CYAN }; 990 991namespace BAR { 992 char global_var3[MAX_BUF_SIZE + 1]; 993 float global_var4[MAX_BUF_SIZE][13]; 994 signed short global_var5[MAX_BUF_SIZE + MAX_BUF_SIZE]; 995 996 int enum_var5[GREEN]; 997 int enum_var6[CYAN]; 998 999 COLOR enum_var7[CYAN][MAX_BUF_SIZE]; 1000} 1001 </pre> 1002 </div> 1003 1004 <p> 1005 Generates: 1006 </p> 1007 1008 <div class="targetlang">array.cl 1009 <pre> 1010(in-package #.*swig-module-name*) 1011 1012(swig-defpackage ("FOO")) 1013(swig-defpackage ("BAR")) 1014 1015(swig-in-package ()) 1016(swig-def-foreign-type "COLOR" :int) 1017(swig-defvar "RED" "ACL_ENUM___RED__SWIG_0" :type :constant) 1018(swig-defvar "GREEN" "ACL_ENUM___GREEN__SWIG_0" :type :constant) 1019(swig-defvar "BLUE" "ACL_ENUM___BLUE__SWIG_0" :type :constant) 1020(swig-defvar "PURPLE" "ACL_ENUM___PURPLE__SWIG_0" :type :constant) 1021(swig-defvar "CYAN" "ACL_ENUM___CYAN__SWIG_0" :type :constant) 1022 1023(swig-in-package ()) 1024 1025(swig-defconstant "MAX_BUF_SIZE" 1024) 1026(swig-in-package ("FOO")) 1027 1028(swig-defun ("global_var1" "ACL_FOO__global_var1_get__SWIG_0" :type :getter) 1029 (:void) 1030 (:returning ((* :int) ) 1031 :strings-convert t) 1032 (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) 1033 1034 1035(swig-defun ("global_var2" "ACL_FOO__global_var2_set__SWIG_0" :type :setter) 1036 ((global_var2 (:array :float 1024) )) 1037 (:returning (:void ) 1038 :strings-convert t) 1039 (let ((SWIG_arg0 global_var2)) 1040 (swig-ff-call SWIG_arg0))) 1041 1042 1043(swig-in-package ()) 1044(swig-in-package ("BAR")) 1045(swig-defun ("global_var3" "ACL_BAR__global_var3_set__SWIG_0" :type :setter) 1046 ((global_var3 (:array :char #|1024+1|#) )) 1047 (:returning (:void ) 1048 :strings-convert t) 1049 (let ((SWIG_arg0 global_var3)) 1050 (swig-ff-call SWIG_arg0))) 1051 1052 1053(swig-defun ("global_var4" "ACL_BAR__global_var4_set__SWIG_0" :type :setter) 1054 ((global_var4 (:array (:array :float 13) 1024) )) 1055 (:returning (:void ) 1056 :strings-convert t) 1057 (let ((SWIG_arg0 global_var4)) 1058 (swig-ff-call SWIG_arg0))) 1059 1060 1061(swig-defun ("global_var4" "ACL_BAR__global_var4_get__SWIG_0" :type :getter) 1062 (:void) 1063 (:returning ((* (:array :float 13)) ) 1064 :strings-convert t) 1065 (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) 1066 1067 1068(swig-defun ("global_var5" "ACL_BAR__global_var5_set__SWIG_0" :type :setter) 1069 ((global_var5 (:array :short #|1024+1024|#) )) 1070 (:returning (:void ) 1071 :strings-convert t) 1072 (let ((SWIG_arg0 global_var5)) 1073 (swig-ff-call SWIG_arg0))) 1074 1075 1076(swig-defun ("enum_var5" "ACL_BAR__enum_var5_set__SWIG_0" :type :setter) 1077 ((enum_var5 (:array :int #|GREEN|#) )) 1078 (:returning (:void ) 1079 :strings-convert t) 1080 (let ((SWIG_arg0 enum_var5)) 1081 (swig-ff-call SWIG_arg0))) 1082 1083 1084(swig-defun ("enum_var6" "ACL_BAR__enum_var6_set__SWIG_0" :type :setter) 1085 ((enum_var6 (:array :int #|CYAN|#) )) 1086 (:returning (:void ) 1087 :strings-convert t) 1088 (let ((SWIG_arg0 enum_var6)) 1089 (swig-ff-call SWIG_arg0))) 1090 1091 1092(swig-defun ("enum_var7" "ACL_BAR__enum_var7_set__SWIG_0" :type :setter) 1093 ((enum_var7 (:array (:array #.(swig-insert-id "COLOR" ()) 1024) #|CYAN|#) )) 1094 (:returning (:void ) 1095 :strings-convert t) 1096 (let ((SWIG_arg0 enum_var7)) 1097 (swig-ff-call SWIG_arg0))) 1098 1099 1100(swig-defun ("enum_var7" "ACL_BAR__enum_var7_get__SWIG_0" :type :getter) 1101 (:void) 1102 (:returning ((* (:array #.(swig-insert-id "COLOR" ()) 1024)) ) 1103 :strings-convert t) 1104 (make-instance 'ff:foreign-pointer :foreign-address (swig-ff-call))) 1105 </pre> 1106 </div> 1107 1108<H3><a name="Allegrocl_nn20"></a>17.3.6 Classes and Structs and Unions (oh my!)</H3> 1109 1110 1111<H4><a name="Allegrocl_nn21"></a>17.3.6.1 CLOS wrapping of</H4> 1112 1113 1114 <p> 1115 Classes, unions, and structs are all treated the same way by the 1116 interface generator. For any of these objects, a 1117 def-foreign-type and a defclass form are generated. For every 1118 function that returns an object (or pointer/reference) of C/C++ 1119 type <tt>X</tt>, the wrapping defun (or defmethod) on the Lisp 1120 side will automatically wrap the pointer returned in an instance 1121 of the apropriate class. This makes it much easier to write and 1122 debug code than if pointers were passed around as a jumble of 1123 integer values. 1124 </p> 1125 1126<H4><a name="Allegrocl_nn22"></a>17.3.6.2 CLOS Inheritance</H4> 1127 1128 1129 <p> 1130 The CLOS class schema generated by the interface mirrors the 1131 inheritance of the classes in foreign code, with the 1132 ff:foreign-pointer class at its root. ff:foreign-pointer is a thin 1133 wrapper for pointers that is made available by the foreign function 1134 interface. It's key benefit is that it may be passed as an argument 1135 to any ff:def-foreign-call that is expecting a pointer as the 1136 parameter. 1137 </p> 1138 1139<H4><a name="Allegrocl_nn23"></a>17.3.6.3 Member fields and functions</H4> 1140 1141 1142 <p> 1143 All public fields will have accessor getter/setter functions 1144 generated for them, as appropriate. All public member functions 1145 will have wrapper functions generated. 1146 </p> 1147 1148 <p> 1149 We currently ignore anything that isn't <tt>public</tt> (i.e. 1150 <tt>private</tt> or <tt>protected</tt>), because the C++ compiler 1151 won't allow the wrapper functions to access such fields. Likewise, 1152 the interface does nothing for <tt>friend</tt> directives, 1153 </p> 1154 1155<H4><a name="Allegrocl_nn24"></a>17.3.6.4 Why not directly access C++ classes using foreign types?</H4> 1156 1157 1158 <p> 1159 The def-foreign-type generated by the SWIG interface is 1160 currently incomplete. We can reliably generate the object layout 1161 of simple structs and unions; they can be allocated via 1162 ff:allocate-fobject, and their member variables accessed 1163 directly using the various ff:fslot-value-* functions. However, 1164 the layout of C++ classes is more complicated. Different 1165 compilers adjust class layout based on inheritance patterns, and 1166 the presence of virtual member functions. The size of member 1167 function pointers vary across compilers as well. As a result, it 1168 is recommended that users of any generated interface not attempt 1169 to access C++ instances via the foreign type system, but instead 1170 use the more robust wrapper functions. 1171 </p> 1172 1173<H3><a name="Allegrocl_nn25"></a>17.3.7 Templates</H3> 1174 1175 1176 1177<H4><a name="Allegrocl_nn26"></a>17.3.7.1 Generating wrapper code for templates</H4> 1178 1179 1180 <p> 1181 SWIG provides support for dealing with templates, but by 1182 default, it will not generate any member variable or function 1183 wrappers for templated classes. In order to create these 1184 wrappers, you need to explicitly tell SWIG to instantiate 1185 them. This is done via the 1186 <a href="SWIGPlus.html#SWIGPlus_nn30"><tt>%template</tt></a> 1187 directive. 1188 </p> 1189 1190<H4><a name="Allegrocl_nn27"></a>17.3.7.2 Implicit Template instantiation</H4> 1191 1192 1193 <p> 1194 While no wrapper code is generated for accessing member 1195 variables, or calling member functions, type code is generated 1196 to include these templated classes in the foreign-type and CLOS 1197 class schema. 1198 </p> 1199 1200<H3><a name="Allegrocl_nn28"></a>17.3.8 Typedef, Templates, and Synonym Types</H3> 1201 1202 1203 <p> 1204 In C/C++ it is possible, via typedef, to have many names refer to 1205 the same <tt>type</tt>. In general, this is not a problem, though 1206 it can lead to confusion. Assume the below C++ header file: 1207 </p> 1208 1209 <div class="code">synonyms.h 1210 <pre> 1211class A { 1212 int x; 1213 int y; 1214}; 1215 1216typedef A Foo; 1217 1218A *xxx(int i); /* sets A->x = A->y = i */ 1219Foo *yyy(int i); /* sets Foo->x = Foo->y = i */ 1220 1221int zzz(A *inst = 0); /* return inst->x + inst->y */ 1222 </pre> 1223 </div> 1224 1225 <p> 1226 The function <tt>zzz</tt> is an overloaded functions; the 1227 foreign function call to it will be wrapped in a 1228 generic-function whose argument will be checked against a type 1229 of <tt>A</tt>. Assuming a simple implementation, a call 1230 to <tt>xxx(1)</tt> will return a pointer to an A object, which 1231 will be wrapped in a CLOS instance of class <tt>A</tt>, and a 1232 call to <tt>yyy(1)</tt> will result in a CLOS instance of 1233 type <tt>Foo</tt> being returned. Without establishing a clear 1234 type relationship between <tt>Foo</tt> and <tt>A</tt>, an 1235 attempt to call <tt>zzz(yyy(1))</tt> will result in an error. 1236 </p> 1237 1238 <p> 1239 We resolve this issue, by noting synonym relationships between 1240 types while generating the interface. A Primary type is selected 1241 (more on this below) from the candidate list of synonyms. For 1242 all other synonyms, intead of generating a distinct CLOS class 1243 definition, we generate a form that expands to: 1244 </p> 1245 <div class="targetlang"> 1246 <tt>(setf (find-class <synonym>) <primary>)</tt> 1247 </div> 1248 <p> 1249 The result is that all references to synonym types in foreign 1250 code, are wrapped in the same CLOS wrapper, and, in particular, 1251 method specialization in wrapping generic functions works as 1252 expected. 1253 </p> 1254 1255 <p> 1256 Given the above header file, synonym.h, a Lisp session would 1257 appear as follows: 1258 </p> 1259 <div class="targetlang"> 1260 <pre> 1261CL-USER> (load "synonym.dll") 1262; Foreign loading synonym.dll. 1263t 1264CL-USER> (load "synonym.cl") 1265; Loading c:\mikel\src\swig\test\synonym.cl 1266t 1267CL-USER> 1268synonym> (setf a (xxx 3)) 1269#<A nil #x3261a0 @ #x207299da> 1270synonym> (setf foo (yyy 10)) 1271#<A nil #x3291d0 @ #x2072e982> 1272synonym> (zzz a) 12736 1274synonym> (zzz foo) 127520 1276synonym> 1277 </pre> 1278 </div> 1279 1280<H4><a name="Allegrocl_nn29"></a>17.3.8.1 Choosing a primary type</H4> 1281 1282 1283 <p> 1284 The choice of a primary type is selected by the following 1285 criteria from a set of synonym types. 1286 </p> 1287 <ul> 1288 <li> 1289 If a synonym type has a class definition, it is the primary type. 1290 </li> 1291 <li> 1292 If a synonym type is a class template and has been explicitly 1293 instantiated via <tt>%template</tt>, it is the primary type. 1294 </li> 1295 <li> 1296 For all other sets of synonymous types, the synonym which is 1297 parsed first becomes the primary type. 1298 </li> 1299 </ul> 1300 1301<H3><a name="Allegrocl_nn30"></a>17.3.9 Function overloading/Parameter defaulting</H3> 1302 1303 1304 <p> 1305 For each possible argument combination, a distinct wrapper 1306 function is created in the .cxx file. On the Lisp side, a 1307 generic functions is defined for each possible arity the 1308 overloaded/defaulted call may have. Each distinct wrapper is 1309 then called from within a defmethod on the appropriate generic 1310 function. These are further wrapped inside a dispatch function 1311 that checks the number of arguments it is called with and passes 1312 them via apply to the appropriate generic-function. This allows 1313 for a single entry point to overloaded functions on the lisp 1314 side. 1315 </p> 1316 1317 <p>Example: 1318 </p> 1319 <div class="code">overload.h: 1320 <pre> 1321 1322class A { 1323 public: 1324 int x; 1325 int y; 1326}; 1327 1328float xxx(int i, int x = 0); /* return i * x */ 1329float xxx(A *inst, int x); /* return x + A->x + A->y */ 1330 </pre> 1331 </div> 1332 1333 <p>Creates the following three wrappers, for each of the possible argument 1334 combinations 1335 </p> 1336 <div class="code">overload_wrap.cxx 1337 <pre> 1338EXPORT void ACL___delete_A__SWIG_0 (A *larg1) { 1339 A *arg1 = (A *) 0 ; 1340 1341 arg1 = larg1; 1342 try { 1343 delete arg1; 1344 1345 } catch (...) { 1346 1347 } 1348} 1349 1350 1351EXPORT float ACL___xxx__SWIG_0 (int larg1, int larg2) { 1352 float lresult = (float)0 ; 1353 int arg1 ; 1354 int arg2 ; 1355 float result; 1356 1357 arg1 = larg1; 1358 arg2 = larg2; 1359 try { 1360 result = (float)xxx(arg1,arg2); 1361 1362 lresult = result; 1363 return lresult; 1364 } catch (...) { 1365 return (float)0; 1366 } 1367} 1368 1369 1370EXPORT float ACL___xxx__SWIG_1 (int larg1) { 1371 float lresult = (float)0 ; 1372 int arg1 ; 1373 float result; 1374 1375 arg1 = larg1; 1376 try { 1377 result = (float)xxx(arg1); 1378 1379 lresult = result; 1380 return lresult; 1381 } catch (...) { 1382 return (float)0; 1383 } 1384} 1385 1386 1387EXPORT float ACL___xxx__SWIG_2 (A *larg1, int larg2) { 1388 float lresult = (float)0 ; 1389 A *arg1 = (A *) 0 ; 1390 int arg2 ; 1391 float result; 1392 1393 arg1 = larg1; 1394 arg2 = larg2; 1395 try { 1396 result = (float)xxx(arg1,arg2); 1397 1398 lresult = result; 1399 return lresult; 1400 } catch (...) { 1401 return (float)0; 1402 } 1403} 1404 </pre> 1405 </div> 1406 1407 <p> 1408 And the following foreign-function-call and method definitions on the 1409 lisp side: 1410 </p> 1411 <div class="targetlang">overload.cl 1412 <pre> 1413(swig-defmethod ("xxx" "ACL___xxx__SWIG_0" :type :function :arity 2) 1414 ((PARM0_i cl:integer :int ) 1415 (PARM1_x cl:integer :int )) 1416 (:returning (:float ) 1417 :strings-convert t) 1418 (let ((SWIG_arg0 PARM0_i)) 1419 (let ((SWIG_arg1 PARM1_x)) 1420 (swig-ff-call SWIG_arg0 SWIG_arg1)))) 1421 1422(swig-defmethod ("xxx" "ACL___xxx__SWIG_1" :type :function :arity 1) 1423 ((PARM0_i cl:integer :int )) 1424 (:returning (:float ) 1425 :strings-convert t) 1426 (let ((SWIG_arg0 PARM0_i)) 1427 (swig-ff-call SWIG_arg0))) 1428 1429(swig-defmethod ("xxx" "ACL___xxx__SWIG_2" :type :function :arity 2) 1430 ((PARM0_inst #.(swig-insert-id "A" () :type :class) (* #.(swig-insert-id "A" ())) ) 1431 (PARM1_x cl:integer :int )) 1432 (:returning (:float ) 1433 :strings-convert t) 1434 (let ((SWIG_arg0 PARM0_inst)) 1435 (let ((SWIG_arg1 PARM1_x)) 1436 (swig-ff-call SWIG_arg0 SWIG_arg1)))) 1437 1438(swig-dispatcher ("xxx" :type :function :arities (1 2))) 1439 </pre> 1440 </div> 1441 1442 <p>And their usage in a sample lisp session: 1443 </p> 1444 <div class="targetlang"> 1445 <pre> 1446overload> (setf a (new_A)) 1447#<A nil #x329268 @ #x206cf612> 1448overload> (setf (A_x a) 10) 144910 1450overload> (setf (A_y a) 20) 145120 1452overload> (xxx 1) 14530.0 1454overload> (xxx 3 10) 145530.0 1456overload> (xxx a 1) 145731.0 1458overload> (xxx a 2) 145932.0 1460overload> 1461 </pre> 1462 </div> 1463 1464<H3><a name="Allegrocl_nn31"></a>17.3.10 Operator wrapping and Operator overloading</H3> 1465 1466 1467 <p> 1468 Wrappers to defined C++ Operators are automatically renamed, using 1469 <tt>%rename</tt>, to the following defaults: 1470 </p> 1471 <div class="code"> 1472 <pre> 1473/* name conversion for overloaded operators. */ 1474#ifdef __cplusplus 1475%rename(__add__) *::operator+; 1476%rename(__pos__) *::operator+(); 1477%rename(__pos__) *::operator+() const; 1478 1479%rename(__sub__) *::operator-; 1480%rename(__neg__) *::operator-() const; 1481%rename(__neg__) *::operator-(); 1482 1483%rename(__mul__) *::operator*; 1484%rename(__deref__) *::operator*(); 1485%rename(__deref__) *::operator*() const; 1486 1487%rename(__div__) *::operator/; 1488%rename(__mod__) *::operator%; 1489%rename(__logxor__) *::operator^; 1490%rename(__logand__) *::operator&; 1491%rename(__logior__) *::operator|; 1492%rename(__lognot__) *::operator~(); 1493%rename(__lognot__) *::operator~() const; 1494 1495%rename(__not__) *::operator!(); 1496%rename(__not__) *::operator!() const; 1497 1498%rename(__assign__) *::operator=; 1499 1500%rename(__add_assign__) *::operator+=; 1501%rename(__sub_assign__) *::operator-=; 1502%rename(__mul_assign__) *::operator*=; 1503%rename(__div_assign__) *::operator/=; 1504%rename(__mod_assign__) *::operator%=; 1505%rename(__logxor_assign__) *::operator^=; 1506%rename(__logand_assign__) *::operator&=; 1507%rename(__logior_assign__) *::operator|=; 1508 1509%rename(__lshift__) *::operator<<; 1510%rename(__lshift_assign__) *::operator<<=; 1511%rename(__rshift__) *::operator>>; 1512%rename(__rshift_assign__) *::operator>>=; 1513 1514%rename(__eq__) *::operator==; 1515%rename(__ne__) *::operator!=; 1516%rename(__lt__) *::operator<; 1517%rename(__gt__) *::operator>; 1518%rename(__lte__) *::operator<=; 1519%rename(__gte__) *::operator>=; 1520 1521%rename(__and__) *::operator&&; 1522%rename(__or__) *::operator||; 1523 1524%rename(__preincr__) *::operator++(); 1525%rename(__postincr__) *::operator++(int); 1526%rename(__predecr__) *::operator--(); 1527%rename(__postdecr__) *::operator--(int); 1528 1529%rename(__comma__) *::operator,(); 1530%rename(__comma__) *::operator,() const; 1531 1532%rename(__member_ref__) *::operator->; 1533%rename(__member_func_ref__) *::operator->*; 1534 1535%rename(__funcall__) *::operator(); 1536%rename(__aref__) *::operator[]; 1537 </pre> 1538 </div> 1539 1540 <p> 1541 Name mangling occurs on all such renamed identifiers, so that wrapper name 1542 generated by <tt>B::operator=</tt> will be <tt>B___eq__</tt>, i.e. 1543 <tt><class-or-namespace>_</tt> has been added. Users may modify 1544 these default names by adding <tt>%rename</tt> directives in their own .i files. 1545 </p> 1546 1547 <p> 1548 Operator overloading can be achieved by adding functions based 1549 on the mangled names of the function. In the following example, 1550 a class B is defined with a Operator== method defined. The 1551 swig <tt>%extend</tt> directive is used to add an overload method 1552 on Operator==. 1553 </p> 1554 1555 <div class="code">opoverload.h 1556 <pre> 1557class B { 1558 public: 1559 int x; 1560 int y; 1561 bool operator==(B const& other) const; 1562}; 1563 </pre> 1564 </div> 1565 1566 <p> 1567 and 1568 </p> 1569 <div class="code">opoverload.i 1570 <pre> 1571%module opoverload 1572 1573%{ 1574#include <fstream> 1575#include "opoverload.h" 1576%} 1577 1578%{ 1579bool B___eq__(B const *inst, int const x) 1580{ 1581 // insert the function definition into the wrapper code before 1582 // the wrapper for it. 1583 // ... do stuff ... 1584} 1585%} 1586 1587%include "opoverload.h" 1588 1589%extend B { 1590 public: 1591 bool __eq__(int const x) const; 1592}; 1593 </pre> 1594 </div> 1595 1596 <p> 1597 Either operator can be called via a single call 1598 to t…
Large files files are truncated, but you can click here to view the full file