PageRenderTime 94ms CodeModel.GetById 67ms app.highlight 15ms RepoModel.GetById 1ms app.codeStats 0ms

/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.&lt;module-name&gt;</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                    =&gt; (swig-defconstant "A" 1)  
 764#define B 'c'                  =&gt; (swig-defconstant "B" #\c)
 765#define C B                    =&gt; (swig-defconstant "C" #\c)
 766#define D 1.0e2                =&gt; (swig-defconstant "D" 1.0d2)
 767#define E 2222                 =&gt; (swig-defconstant "E" 2222)
 768#define F (unsigned int)2222   =&gt; no code generated
 769#define G 1.02e2f              =&gt; (swig-defconstant "G" 1.02f2)
 770#define H foo                  =&gt; 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                =&gt; (swig-defconstant "I" (+ 1 2222))
 793#define J 1|2                  =&gt; (swig-defconstant "J" (logior 1 2))
 794#define Y 1 + 2 * 3 + 4        =&gt; (swig-defconstant "Y" (* (+ 1 2) (+ 3 4)))
 795#define Y1 (1 + 2) * (3 + 4)   =&gt; (swig-defconstant "Y1" (* (+ 1 2) (+ 3 4)))
 796#define Y2 1 * 2 + 3 * 4       =&gt; (swig-defconstant "Y2" (* 1 (+ 2 3) 4))  ;; WRONG
 797#define Y3 (1 * 2) + (3 * 4)   =&gt; (swig-defconstant "Y3" (* 1 (+ 2 3) 4))  ;; WRONG
 798#define Z 1 + 2 - 3 + 4 * 5    =&gt; (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&gt; (load "globalvar.dll")
 867; Foreign loading globalvar.dll.
 868t
 869user&gt; (load "globalvar.cl")
 870; Loading c:\mikel\src\swig\test\globalvar.cl
 871t
 872user&gt; 
 873globalvar&gt; (globalvar.nnn::global_var)
 8742
 875globalvar&gt; (globalvar.nnn::glob_float)
 8762.0
 877globalvar&gt; (setf (globalvar.nnn::glob_float) 3.0)
 8783.0
 879globalvar&gt; (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-&gt;x = A-&gt;y = i */
1219Foo *yyy(int i);       /* sets Foo-&gt;x = Foo-&gt;y = i */
1220
1221int zzz(A *inst = 0);  /* return inst-&gt;x + inst-&gt;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 &lt;synonym&gt;) &lt;primary&gt;)</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&gt; (load "synonym.dll")
1262; Foreign loading synonym.dll.
1263t
1264CL-USER&gt; (load "synonym.cl")
1265; Loading c:\mikel\src\swig\test\synonym.cl
1266t
1267CL-USER&gt; 
1268synonym&gt; (setf a (xxx 3))
1269#&lt;A nil #x3261a0 @ #x207299da&gt;
1270synonym&gt; (setf foo (yyy 10))
1271#&lt;A nil #x3291d0 @ #x2072e982&gt;
1272synonym&gt; (zzz a)
12736
1274synonym&gt; (zzz foo)
127520
1276synonym&gt; 
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-&gt;x + A-&gt;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&gt; (setf a (new_A))
1447#&lt;A nil #x329268 @ #x206cf612&gt;
1448overload&gt; (setf (A_x a) 10)
144910
1450overload&gt; (setf (A_y a) 20)
145120
1452overload&gt; (xxx 1)
14530.0
1454overload&gt; (xxx 3 10)
145530.0
1456overload&gt; (xxx a 1)
145731.0
1458overload&gt; (xxx a 2)
145932.0
1460overload&gt; 
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&amp;;
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&amp;=;
1507%rename(__logior_assign__)   *::operator|=;
1508
1509%rename(__lshift__)	     *::operator&lt;&lt;;
1510%rename(__lshift_assign__)   *::operator&lt;&lt;=;
1511%rename(__rshift__)	     *::operator&gt;&gt;;
1512%rename(__rshift_assign__)   *::operator&gt;&gt;=;
1513
1514%rename(__eq__)		     *::operator==;
1515%rename(__ne__)		     *::operator!=;
1516%rename(__lt__)		     *::operator&lt;;
1517%rename(__gt__)		     *::operator&gt;;
1518%rename(__lte__)	     *::operator&lt;=;
1519%rename(__gte__)	     *::operator&gt;=;
1520
1521%rename(__and__)	     *::operator&amp;&amp;;
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-&gt;;
1533%rename(__member_func_ref__) *::operator-&gt;*;
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>&lt;class-or-namespace&gt;_</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&amp; 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 &lt;fstream&gt;
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