Doc/Manual/Allegrocl.html

   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_nn1"></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>
  97 This chapter describes SWIG's support of Allegro Common Lisp. Allegro
  98 CL is a full-featured implementation of the Common Lisp language
  99 standard that includes many vendor-specific enhancements and add-on
 100 modules for increased usability.
 101 </p>
 102
 103 <p>
 104 One such module included in Allegro CL is the Foreign Functions
 105 Interface (FFI). This module, tailored primarily toward interfacing
 106 with C/C++ and, historically, Fortran, provides a means by which
 107 compiled foreign code can be loaded into a running lisp
 108 environment and executed. The interface supports the calling of
 109 foreign functions and methods, allows for executing lisp routines
 110 from foreign code (callbacks), and the passing of data between foreign
 111 and lisp code.
 112 </p>
 113
 114 <p>
 115 The goal of this module is to make it possible to quickly generate the
 116 necessary foreign function definitions so one can make use of C/C++
 117 foreign libraries directly from lisp without the tedium of having to
 118 code them by hand. When necessary, it will also generate further C/C++
 119 code that will need to be linked with the intended library for proper
 120 interfacing from lisp. It has been designed with an eye toward
 121 flexibility. Some foreign function calls may release the heap, while
 122 other should not. Some foreign functions should automatically convert
 123 lisp strings into native strings, while others should not. These
 124 adjustments and many more are possible with the current module.
 125 </p>
 126
 127 <p>
 128 It is significant to note that, while this is a vendor-specific
 129 module, we would like to acknowledge the current and ongoing
 130 work by developers in the open source lisp community that are
 131 working on similar interfaces to implementation-independent
 132 foreign function interfaces (UFFI or CFFI, for example). Such
 133 work can only benefit the lisp community, and we would not
 134 be unhappy to see some enterprising folk use this work to add
 135 to 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>
 145 If you're reading this, you must have some library you need to
 146 generate an interface for. In order for SWIG to do this work, however,
 147 it needs a bit of information about how it should go about creating
 148 your interface, and what you are interfacing to.
 149 </p>
 150
 151 <p>
 152 SWIG expects a description of what in the foreign interface you wish
 153 to connect to. It must consisting of C/C++ declarations and special
 154 SWIG directives. SWIG can be furnished with a header file, but an
 155 interface can also be generated without library headers by supplying a
 156 simple text file--called the interface file, which is typically named
 157 with a <tt>.i</tt> extension--containing any foreign declarations of
 158 identifiers you wish to use. The most common approach is to use a an
 159 interface file with directives to parse the needed headers. A straight
 160 parse of library headers will result in usable code, but SWIG
 161 directives provides much freedom in how a user might tailor the
 162 generated code to their needs or style of coding.
 163 </p>
 164
 165 <p>
 166 Note that SWIG does not require any function definitions; the
 167 declarations of those functions is all that is necessary. Be careful
 168 when tuning the interface as it is quite possible to generate code
 169 that will not load or compile.
 170 </p>
 171
 172 <p>
 173 An example interface file is shown below. It makes use of two SWIG
 174 directives, one of which requests that the declarations in a header
 175 file be used to generate part of the interface, and also includes an
 176 additional declaration to be added.</p>
 177
 178 <div class="code">example.i
 179 <pre>
 180 %module example
 181
 182 %include "header.h"
 183
 184 int 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>
 191 int 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>
 225 The generated file contains calls to internal swig helper
 226 functions. In this case there are two calls to swig-defun.
 227 These calls will expand into code that will make the appropriate
 228 definitions using the Allegro FFI. Note also, that this code is
 229 <b>erroneous</b>. Function overloading is not supported in C, and this
 230 code will not compile even though SWIG did not complain.
 231 </p>
 232
 233 <p>
 234 In order to generate a C interface to Allegro CL using this code run
 235 swig 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>
 245 When 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>
 255 As a result of running one of the above commands, a file named <tt>example.cl</tt>
 256 will 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
 258 facilitate access to C++ methods, enumeration values, and constant values.
 259 Wrapper functions are necessary in C++ due to the lack of a standard for mangling
 260 the names of symbols across all C++ compilers. These wrapper functions are
 261 exported from the shared library as appropriate, using the C name mangling
 262 convention. The lisp code that is generated will interface to your foreign
 263 library through these wrappers.
 264 </p>
 265
 266 <p>
 267 It is possible to disable the creation of the .cxx file when generating a C
 268 interface by using the -nocwrap command-line argument. For interfaces that
 269 don't contain complex enum or constant expressions, contain nested struct/union
 270 declarations, or doesn't need to use many of the SWIG customization featuers,
 271 this will result in a more streamlined, direct interface to the
 272 intended module.
 273 </p>
 274
 275 <p>
 276 The generated wrapper file is below. It contains very simple
 277 wrappers by default, that simply pass the arguments to the
 278 actual function.
 279 </p>
 280
 281 <div class="code">example_wrap.i
 282 <pre>
 283    ... lots of SWIG internals ...
 284
 285 EXPORT 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
 302 EXPORT 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>
 321 And again, the generated lisp code. Note that it differs from
 322 what 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
 350 a swig-dispatcher form. This provides a single functional interface for
 351 all overloaded routines. A more detailed description of this features
 352 is to be found in the section titled <b>Function overloading/Parameter defaulting</b>.
 353
 354 <p>
 355 In order to load a C++ interface, you will need to build a shared library
 356 from example_wrap.cxx. Be sure to link in the actual library you created
 357 the interface for, as well as any other dependent shared libraries. For
 358 example, if you intend to be able to call back into lisp, you will also
 359 need to link in the Allegro shared library. The library you create from
 360 the 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>
 367 There are three Allegro CL specific command-line option:
 368 </p>
 369
 370 <div class="shell">
 371 <pre>
 372 swig -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>
 395 See <a href="#Allegrocl_nn47">Section 17.5 Identifier converter
 396 functions</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>
 403 It is often necessary to include user-defined code into the
 404 automatically generated interface files. For example, when building
 405 a C++ interface, example_wrap.cxx will likely not compile unless
 406 you add a <tt>#include "header.h"</tt> directive. This can be done
 407 using 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
 420 int fact(int n);
 421 </pre>
 422 </div>
 423
 424 <p>
 425 Additional sections have been added for inserting into the
 426 generated 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>
 434 Note 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>
 443 New 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
 446 interested 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
 532 int foo(float f1, float f2);
 533 int foo(float f1, char c2);
 534
 535 void bar(void *lisp_fn);
 536
 537 char *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
 690 namespace 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>
 822 namespace 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>
 866 user&gt; (load "globalvar.dll")
 867 ; Foreign loading globalvar.dll.
 868 t
 869 user&gt; (load "globalvar.cl")
 870 ; Loading c:\mikel\src\swig\test\globalvar.cl
 871 t
 872 user&gt;
 873 globalvar&gt; (globalvar.nnn::global_var)
 874 2
 875 globalvar&gt; (globalvar.nnn::glob_float)
 876 2.0
 877 globalvar&gt; (setf (globalvar.nnn::glob_float) 3.0)
 878 3.0
 879 globalvar&gt; (globalvar.nnn::glob_float)
 880 3.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>
 910 enum COL { RED, GREEN, BLUE };
 911 enum 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>
 934 EXPORT const int ACL_ENUM___RED__SWIG_0 = RED;
 935 EXPORT const int ACL_ENUM___GREEN__SWIG_0 = GREEN;
 936 EXPORT const int ACL_ENUM___BLUE__SWIG_0 = BLUE;
 937 EXPORT const int ACL_ENUM___FOO1__SWIG_0 = FOO1;
 938 EXPORT const int ACL_ENUM___FOO2__SWIG_0 = FOO2;
 939 EXPORT 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
 983 namespace FOO {
 984   int global_var1[13];
 985   float global_var2[MAX_BUF_SIZE];
 986
 987 }
 988
 989 enum COLOR { RED = 10, GREEN = 20, BLUE, PURPLE = 50, CYAN };
 990
 991 namespace 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>
1211 class A {
1212    int x;
1213    int y;
1214 };
1215
1216 typedef A Foo;
1217
1218 A *xxx(int i);         /* sets A-&gt;x = A-&gt;y = i */
1219 Foo *yyy(int i);       /* sets Foo-&gt;x = Foo-&gt;y = i */
1220
1221 int 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>
1261 CL-USER&gt; (load "synonym.dll")
1262 ; Foreign loading synonym.dll.
1263 t
1264 CL-USER&gt; (load "synonym.cl")
1265 ; Loading c:\mikel\src\swig\test\synonym.cl
1266 t
1267 CL-USER&gt;
1268 synonym&gt; (setf a (xxx 3))
1269 #&lt;A nil #x3261a0 @ #x207299da&gt;
1270 synonym&gt; (setf foo (yyy 10))
1271 #&lt;A nil #x3291d0 @ #x2072e982&gt;
1272 synonym&gt; (zzz a)
1273 6
1274 synonym&gt; (zzz foo)
1275 20
1276 synonym&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
1322 class A {
1323  public:
1324   int x;
1325   int y;
1326 };
1327
1328 float xxx(int i, int x = 0);   /* return i * x */
1329 float 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>
1338 EXPORT 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
1351 EXPORT 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
1370 EXPORT 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
1387 EXPORT 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>
1446 overload&gt; (setf a (new_A))
1447 #&lt;A nil #x329268 @ #x206cf612&gt;
1448 overload&gt; (setf (A_x a) 10)
1449 10
1450 overload&gt; (setf (A_y a) 20)
1451 20
1452 overload&gt; (xxx 1)
1453 0.0
1454 overload&gt; (xxx 3 10)
1455 30.0
1456 overload&gt; (xxx a 1)
1457 31.0
1458 overload&gt; (xxx a 2)
1459 32.0
1460 overload&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>
1557 class 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 %{
1579 bool 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 the dispatch function:
1599     </p>
1600     <div class="targetlang">
1601     <pre>
1602 opoverload&gt; (B___eq__ x1 x2)
1603 nil
1604 opoverload&gt; (B___eq__ x1 3)
1605 nil
1606 opoverload&gt;
1607     </pre>
1608     </div>
1609
1610 <H3><a name="Allegrocl_nn32"></a>17.3.11 Varargs</H3>
1611
1612
1613     <p>
1614       Variable length argument lists are not supported, by default. If
1615       such a function is encountered, a warning will generated to
1616       stderr. Varargs are supported via the SWIG <tt>%vararg</tt>
1617       directive. This directive allows you to specify a (finite)
1618       argument list which will be inserted into the wrapper in place
1619       of the variable length argument indicator.  As an example,
1620       consider the function <tt>printf()</tt>. It's declaration would
1621       appear as follows:
1622     </p>
1623
1624     <p>
1625       See the following section
1626       on <a href="Varargs.html#Varargs">Variable Length arguments</a>
1627       provides examples on how <tt>%vararg</tt> can be used, along
1628       with other ways such functions can be wrapped.
1629     </p>
1630
1631 <H3><a name="Allegrocl_nn33"></a>17.3.12 C++ Exceptions</H3>
1632
1633
1634     <p>
1635       Each C++ wrapper includes a handler to catch any exceptions that may
1636       be thrown while in foreign code. This helps prevent simple C++ errors
1637       from killing the entire lisp process. There is currently no mechanism
1638       to have these exceptions forwarded to the lisp condition system, nor
1639       has any explicit support of the exception related SWIG typemaps been
1640       implemented.
1641     </p>
1642
1643 <H3><a name="Allegrocl_nn34"></a>17.3.13 Pass by value, pass by reference</H3>
1644
1645
1646     <p>
1647       Allegro CL does not support the passing of non-primitive foreign
1648       structures by value. As a result, SWIG must automatically detect
1649       and convert function parameters and return values to pointers
1650       whenever necessary. This is done via the use of <tt>typemaps</tt>,
1651       and should not require any fine tuning by the user, even for
1652       newly defined types.
1653     </p>
1654
1655 <H2><a name="Allegrocl_nn35"></a>17.4 Typemaps</H2>
1656
1657
1658 <p>
1659   SWIG Typemaps provide a powerful tool for automatically generating
1660   code to handle various menial tasks required of writing an interface
1661   to foreign code. The purpose of this section is to describe each of
1662   the typemaps used by the Allegro CL module. Please read the chapter
1663   on <a href="Typemaps.html#Typemaps">Typemaps</a> for more information.
1664 </p>
1665
1666 <H3><a name="Allegrocl_nn36"></a>17.4.1 Code Generation in the C++ Wrapper</H3>
1667
1668
1669
1670     <p>
1671       Every C++ wrapper generated by SWIG takes the following form:
1672     </p>
1673
1674     <div class="diagram">
1675     <pre>
1676 return-val wrapper-name(parm0, parm1, ..., parmN)
1677 {
1678    return-val lresult;   /* return value from wrapper */
1679    &lt;local-declaration&gt;
1680    ... results;          /* return value from function call */
1681
1682    &lt;binding locals to parameters&gt;
1683
1684    try {
1685       result = function-name(local0, local1, ..., localN);
1686
1687       &lt;convert and bind result to lresult&gt;
1688
1689       return lresult;
1690    catch (...) {
1691       return (int)0;
1692    }
1693     </pre>
1694     </div>
1695
1696 <H4><a name="Allegrocl_nn37"></a>17.4.1.1 IN Typemap</H4>
1697
1698
1699     <p>
1700       the <tt>in</tt> typemap is used to generate code to convert parameters
1701       passed to C++ wrapper functions into the arguments desired for the
1702       call being wrapped. That is, it fills in the code for the
1703       <tt>&lt;binding locals to parameters&gt;</tt> section above. We
1704       use this map to automatically convert parameters passed by
1705       reference to the wrapper function into by-value arguments for
1706       the wrapped call, and also to convert boolean values, which are
1707       passed as integers from lisp (by default), into the appropriate
1708       type for the language of code being wrapped.
1709     </p>
1710
1711     <p>These are the default specifications for the IN typemap. Here,
1712       <tt>$input</tt> refers to the parameter code is being generated
1713       for, and <tt>$1</tt> is the local variable to which it is
1714       being assigned. The default settings of this typemap are as follows:
1715     </p>
1716
1717     <div class="code">
1718     <pre>
1719 %typemap(in) bool                          "$1 = (bool)$input;";
1720 %typemap(in) char, unsigned char, signed char,
1721              short, signed short, unsigned short,
1722              int, signed int, unsigned int,
1723              long, signed long, unsigned long,
1724              float, double, long double, char *, void *, void,
1725              enum SWIGTYPE, SWIGTYPE *,
1726              SWIGTYPE[ANY], SWIGTYPE &amp;     "$1 = $input;";
1727 %typemap(in) SWIGTYPE                      "$1 = *$input;";
1728     </pre>
1729     </div>
1730
1731 <H4><a name="Allegrocl_nn38"></a>17.4.1.2 OUT Typemap</H4>
1732
1733
1734     <p>
1735       The <tt>out</tt> typemap is used to generate code to form the
1736       return value of the wrapper from the return value of the wrapped
1737       function. This code is placed in the &lt;convert and bind result to lresult&gt;
1738       section of the above code diagram. It's default mapping is as follows:
1739     </p>
1740
1741     <div class="code">
1742     <pre>
1743 %typemap(out) bool                          "$result = (int)$1;";
1744 %typemap(out) char, unsigned char, signed char,
1745               short, signed short, unsigned short,
1746               int, signed int, unsigned int,
1747               long, signed long, unsigned long,
1748               float, double, long double, char *, void *, void,
1749               enum SWIGTYPE, SWIGTYPE *,
1750               SWIGTYPE[ANY], SWIGTYPE &amp;    "$result = $1;";
1751 %typemap(out) SWIGTYPE                     "$result = new $1_type($1);";
1752     </pre>
1753     </div>
1754
1755 <H4><a name="Allegrocl_nn39"></a>17.4.1.3 CTYPE Typemap</H4>
1756
1757
1758     <p>
1759       This typemap is not used for code generation, but purely for the
1760       transformation of types in the parameter list of the wrapper function.
1761       It's primary use is to handle by-value to by-reference conversion in the
1762       wrappers parameter list. Its default settings are:
1763     </p>
1764
1765     <div class="code">
1766     <pre>
1767 %typemap(ctype) bool                       "int";
1768 %typemap(ctype) char, unsigned char, signed char,
1769                 short, signed short, unsigned short,
1770                 int, signed int, unsigned int,
1771                 long, signed long, unsigned long,
1772                 float, double, long double, char *, void *, void,
1773                 enum SWIGTYPE, SWIGTYPE *,
1774                 SWIGTYPE[ANY], SWIGTYPE &amp;  "$1_ltype";
1775 %typemap(ctype) SWIGTYPE                   "$&amp;1_type";
1776     </pre>
1777     </div>
1778
1779     <p>
1780       These three typemaps are specifically employed by the the
1781       Allegro CL interface generator. SWIG also implements a number of
1782       other typemaps that can be used for generating code in the C/C++
1783       wrappers. You can read about
1784       these <a href="Typemaps.html#Typemaps_nn25">common typemaps</a> here.
1785     </p>
1786
1787 <H3><a name="Allegrocl_nn40"></a>17.4.2 Code generation in Lisp wrappers</H3>
1788
1789
1790     <p>
1791       A number of custom typemaps have also been added to facilitate
1792       the generation of code in the lisp side of the interface. These
1793       are described below. The basic code generation structure is
1794       applied as a series of nested expressions, one for each
1795       parameter, then one for manipulating the return value, and last,
1796       the foreign function call itself.
1797     </p>
1798
1799     <p>
1800       Note that the typemaps below use fully qualified symbols where
1801       necessary. Users writing their own typemaps should do likewise.
1802       See the explanation in the last paragraph of
1803       <a href="#Allegrocl_nn15">16.3.1 Namespaces</a> for details.
1804     </p>
1805
1806 <H4><a name="Allegrocl_nn41"></a>17.4.2.1 LIN Typemap</H4>
1807
1808
1809     <p>
1810       The LIN typemap allows for the manipulating the lisp objects
1811       passed as arguments to the wrapping defun before passing them to
1812       the foreign function call. For example, when passing lisp
1813       strings to foreign code, it is often necessary to copy the
1814       string into a foreign structure of type (:char *) of appropriate
1815       size, and pass this copy to the foreign call. Using the LIN
1816       typemap, one could arrange for the stack-allocation of a foreign
1817       char array, copy your string into it, and not have to worry
1818       about freeing the copy after the function returns.
1819     </p>
1820
1821     <p>The LIN typemap accepts the following <tt>$variable</tt> references.
1822     </p>
1823       <ul>
1824         <li><tt>$in</tt> - expands to the name of the parameter being
1825           applied to this typemap
1826         </li>
1827         <li><tt>$out</tt> - expands to the name of the local variable
1828           assigned to this typemap
1829         </li>
1830         <li><tt>$in_fftype</tt> - the foreign function type of the C type.</li>
1831         <li><tt>$*in_fftype</tt> - the foreign function type of the C type
1832           with one pointer removed. If there is no pointer, then $*in_fftype
1833           is the same as $in_fftype.
1834         </li>
1835         <li><tt>$body</tt> - very important. Instructs SWIG where
1836           subsequent code generation steps should be inserted into the
1837           current typemap.  Leaving out a <tt>$body</tt> reference
1838           will result in lisp wrappers that do very little by way of
1839           calling into foreign code. Not recommended.
1840         </li>
1841       </ul>
1842
1843     <div class="code">
1844     <pre>
1845 %typemap(lin)   SWIGTYPE        "(cl:let (($out $in))\n  $body)";
1846     </pre>
1847     </div>
1848
1849 <H4><a name="Allegrocl_nn42"></a>17.4.2.2 LOUT Typemap</H4>
1850
1851
1852     <p>
1853       The LOUT typemap is the means by which we effect the wrapping of
1854       foreign pointers in CLOS instances. It is applied after all LIN
1855       typemaps, and immediately before the actual foreign-call.
1856     </p>
1857
1858     <p>The LOUT typemap uses the following $variable
1859     </p>
1860       <ul>
1861         <li><tt>$lclass</tt> - Expands to the CLOS class that
1862           represents foreign-objects of the return type matching this
1863           typemap.
1864         </li>
1865         <li><tt>$body</tt> - Same as for the LIN map. Place this
1866           variable where you want the foreign-function call to occur.
1867         </li>
1868         <li><tt>$ldestructor</tt> - Expands to the symbol naming the destructor for this
1869           class ($lclass) of object. Allows you to insert finalization or automatic garbage
1870           collection into the wrapper code (see default mappings below).
1871         </li>
1872       </ul>
1873
1874     <div class="code">
1875     <pre>
1876 %typemap(lout) bool, char, unsigned char, signed char,
1877                short, signed short, unsigned short,
1878                int, signed int, unsigned int,
1879                long, signed long, unsigned long,
1880                float, double, long double, char *, void *, void,
1881                enum SWIGTYPE    "$body";
1882 %typemap(lout) SWIGTYPE[ANY], SWIGTYPE *,
1883                SWIGTYPE &amp;       "(cl:make-instance '$lclass :foreign-address $body)";
1884 %typemap(lout) SWIGTYPE    "(cl:let* ((address $body)\n
1885                             (ACL_result (cl:make-instance '$lclass :foreign-address address)))\n
1886                             (cl:unless (cl::zerop address)\n
1887                             (excl:schedule-finalization ACL_result #'$ldestructor))\n
1888                              ACL_result)";
1889     </pre>
1890     </div>
1891
1892 <H4><a name="Allegrocl_nn43"></a>17.4.2.3 FFITYPE Typemap</H4>
1893
1894
1895
1896     <p>
1897       The FFITYPE typemap works as a helper for a body of code that
1898       converts C/C++ type specifications into Allegro CL foreign-type
1899       specifications. These foreign-type specifications appear in
1900       ff:def-foreing-type declarations, and in the argument list and
1901       return values of ff:def-foreign-calls. You would modify this
1902       typemap if you want to change how the FFI passes through
1903       arguments of a given type. For example, if you know that a
1904       particular compiler represents booleans as a single byte, you
1905       might add an entry for:
1906     </p>
1907
1908     <div class="code">
1909     <pre>
1910 %typemap(ffitype) bool ":unsigned-char";
1911     </pre>
1912     </div>
1913
1914     <p>
1915       Note that this typemap is pure type transformation, and is not
1916       used in any code generations step the way the LIN and LOUT
1917       typemaps are. The default mappings for this typemap are:
1918     </p>
1919
1920     <div class="code">
1921     <pre>
1922 %typemap(ffitype) bool ":int";
1923 %typemap(ffitype) char ":char";
1924 %typemap(ffitype) unsigned char ":unsigned-char";
1925 %typemap(ffitype) signed char ":char";
1926 %typemap(ffitype) short, signed short ":short";
1927 %typemap(ffitype) unsigned short ":unsigned-short";
1928 %typemap(ffitype) int, signed int ":int";
1929 %typemap(ffitype) unsigned int ":unsigned-int";
1930 %typemap(ffitype) long, signed long ":long";
1931 %typemap(ffitype) unsigned long ":unsigned-long";
1932 %typemap(ffitype) float ":float";
1933 %typemap(ffitype) double ":double";
1934 %typemap(ffitype) char * "(* :char)";
1935 %typemap(ffitype) void * "(* :void)";
1936 %typemap(ffitype) void ":void";
1937 %typemap(ffitype) enum SWIGTYPE ":int";
1938 %typemap(ffitype) SWIGTYPE &amp; "(* :void)";
1939     </pre>
1940     </div>
1941
1942 <H4><a name="Allegrocl_nn44"></a>17.4.2.4 LISPTYPE Typemap</H4>
1943
1944
1945     <p>
1946       This is another type only transformation map, and is used to
1947       provide the lisp-type, which is the optional third argument in
1948       argument specifier in a ff:def-foreign-call form. Specifying a
1949       lisp-type allows the foreign call to perform type checking on
1950       the arguments passed in. The default entries in this typemap are:
1951     </p>
1952
1953     <div class="code">
1954     <pre>
1955 %typemap(lisptype) bool "cl:boolean";
1956 %typemap(lisptype) char "cl:character";
1957 %typemap(lisptype) unsigned char "cl:integer";
1958 %typemap(lisptype) signed char "cl:integer";
1959     </pre>
1960     </div>
1961
1962 <H4><a name="Allegrocl_nn45"></a>17.4.2.5 LISPCLASS Typemap</H4>
1963
1964
1965     <p>
1966       The LISPCLASS typemap is used to generate the method signatures
1967       for the generic-functions which wrap overloaded functions and
1968       functions with defaulted arguments. The default entries are:
1969     </p>
1970
1971     <div class="code">
1972     <pre>
1973 %typemap(lispclass) bool "t";
1974 %typemap(lispclass) char "cl:character";
1975 %typemap(lispclass) unsigned char, signed char,
1976                     short, signed short, unsigned short,
1977                     int, signed int, unsigned int,
1978                     long, signed long, unsigned long,
1979                     enum SWIGTYPE       "cl:integer";
1980 %typemap(lispclass) float "cl:single-float";
1981 %typemap(lispclass) double "cl:double-float";
1982 %typemap(lispclass) char * "cl:string";
1983     </pre>
1984     </div>
1985
1986 <H3><a name="Allegrocl_nn46"></a>17.4.3 Modifying SWIG behavior using typemaps</H3>
1987
1988
1989     <p>
1990       The following example shows how we made use of the above
1991       typemaps to add support for the wchar_t type.
1992     </p>
1993
1994     <div class="code">
1995     <pre>
1996 %typecheck(SWIG_TYPECHECK_UNICHAR) wchar_t { $1 = 1; };
1997
1998 %typemap(in)        wchar_t "$1 = $input;";
1999 %typemap(lin)       wchar_t "(cl:let (($out (cl:char-code $in)))\n  $body)";
2000 %typemap(lin)       wchar_t* "(excl:with-native-string
2001                                          ($out $in
2002                                           :external-format #+little-endian :fat-le
2003                                                            #-little-endian :fat)\n
2004                                  $body)"
2005
2006 %typemap(out)       wchar_t "$result = $1;";
2007 %typemap(lout)      wchar_t "(cl:code-char $body)";
2008 %typemap(lout)      wchar_t* "(excl:native-to-string $body
2009                                           :external-format #+little-endian :fat-le
2010                                                            #-little-endian :fat)";
2011
2012 %typemap(ffitype)   wchar_t ":unsigned-short";
2013 %typemap(lisptype)  wchar_t "";
2014 %typemap(ctype)     wchar_t "wchar_t";
2015 %typemap(lispclass) wchar_t "cl:character";
2016 %typemap(lispclass) wchar_t* "cl:string";
2017     </pre>
2018     </div>
2019
2020 <H2><a name="Allegrocl_nn47"></a>17.5 Identifier Converter functions</H2>
2021
2022
2023 <H3><a name="Allegrocl_nn48"></a>17.5.1 Creating symbols in the lisp environment</H3>
2024
2025
2026 <p>
2027   Various symbols must be generated in the lisp environment to which
2028   class definitions, functions, constants, variables, etc. must be
2029   bound. Rather than force a particular convention for naming these
2030   symbols, an identifier (to symbol) conversion function is used. A
2031   user-defined identifier-converter can then implement any symbol
2032   naming, case-modifying, scheme desired.
2033 </p>
2034
2035 <p>
2036   In generated SWIG code, whenever some interface object must be
2037   referenced by its lisp symbol, a macro is inserted that calls the
2038   identifier-converter function to generate the appropriate symbol
2039   reference. It is therefore expected that the identifier-converter
2040   function reliably return the same (eq) symbol given the same set
2041   of arguments.
2042 </p>
2043
2044 <H3><a name="Allegrocl_nn49"></a>17.5.2 Existing identifier-converter functions</H3>
2045
2046
2047   <p>Two basic identifier routines have been defined.
2048 <H4><a name="Allegrocl_nn50"></a>17.5.2.1 identifier-convert-null</H4>
2049
2050
2051     <p>
2052       No modification of the identifier string is performed. Based on
2053       other arguments, the identifier may be concatenated with other
2054       strings, from which a symbol will be created.
2055     </p>
2056
2057 <H4><a name="Allegrocl_nn51"></a>17.5.2.2 identifier-convert-lispify</H4>
2058
2059
2060     <p>
2061       All underscores in the identifier string are converted to
2062       hyphens. Otherwise, identifier-convert-lispify performs the
2063       same symbol transformations.
2064     </p>
2065
2066 <H4><a name="Allegrocl_nn52"></a>17.5.2.3 Default identifier to symbol conversions</H4>
2067
2068
2069     <p>
2070       Check the definitions of the above two default
2071       identifier-converters in <tt>Lib/allegrocl/allegrocl.swg</tt> for
2072       default naming conventions.
2073     </p>
2074
2075 <H3><a name="Allegrocl_nn53"></a>17.5.3 Defining your own identifier-converter</H3>
2076
2077
2078 <p>
2079   A user-defined identifier-converter function should conform to the following
2080   specification:
2081 </p>
2082
2083 <div class="targetlang">
2084 <pre>
2085 (defun identifier-convert-fn (id &amp;key type class arity) ...body...)
2086 result ==&gt; symbol or (setf symbol)
2087 </pre>
2088 </div>
2089
2090 <p>The <tt>ID</tt> argument is a string representing an identifier in the
2091 foreign environment.
2092 </p>
2093
2094 <p>
2095 The :type keyword argument provides more information on the type of
2096 identifier. It's value is a symbol. This allows the
2097 identifier-converter to apply different heuristics when mapping
2098 different types of identifiers to symbols. SWIG will generate calls
2099 to your identifier-converter using the following types.
2100 </p>
2101
2102 <ul>
2103   <li>:class - names a CLOS class.</li>
2104   <li>:constant - names a defconstant</li>
2105   <li>:constructor - names a function for creating a foreign object</li>
2106   <li>:destructor - names a function for freeing a foreign object</li>
2107   <li>:function - names a CLOS wrapping defmethod or defun.</li>
2108   <li>:ff-operator - names a foreign call defined via ff:def-foreign-call</li>
2109   <li>:getter - getter function</li>
2110   <li>:namespace - names a C++ namespace</li>
2111   <li>:setter - names a setter function. May return a (setf symbol) reference</li>
2112   <li>:operator - names a C++ operator, such as Operator=, Operator*.</li>
2113   <li>:slot - names a slot in a struct/class/union declaration.</li>
2114   <li>:type - names a foreign-type defined via ff:def-foreign-type.</li>
2115   <li>:variable - names a variable defined via ff:def-foreign-variable.</li>
2116 </ul>
2117
2118 <p>
2119 The :class keyword argument is a string naming a foreign
2120 class. When non-nil, it indicates that the current identifier has
2121 scope in the specified class.
2122 </p>
2123
2124 <p>
2125 The :arity keyword argument only appears in swig:swig-defmethod forms
2126 generated for overloaded functions. It's value is an integer
2127 indicating the number of arguments passed to the routine indicated by
2128 this identifier.
2129 </p>
2130
2131 <H3><a name="Allegrocl_nn54"></a>17.5.4 Instructing SWIG to use a particular identifier-converter</H3>
2132
2133
2134 <p>
2135   By default, SWIG will use identifier-converter-null. To specify
2136   another convert function, use the <tt>-identifier-converter</tt>
2137   command-line argument. The value should be a string naming the
2138   function you wish the interface to use instead, when generating
2139   symbols. ex:
2140 </p>
2141
2142 <div class="code">
2143 <pre>
2144 % swig -allegrocl -c++ -module mymodule -identifier-converter my-identifier-converter
2145 </pre>
2146 </div>
2147
2148
2149 </body>
2150 </html>