Doc/Manual/Lisp.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>SWIG and Common Lisp</title>
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 </head>
   7
   8 <body bgcolor="#ffffff">
   9 <H1><a name="Lisp_nn1"></a>22 SWIG and Common Lisp</H1>
  10 <!-- INDEX -->
  11 <div class="sectiontoc">
  12 <ul>
  13 <li><a href="#Lisp_nn2">Allegro Common Lisp</a>
  14 <li><a href="#Lisp_nn3">Common Foreign Function Interface(CFFI)</a>
  15 <ul>
  16 <li><a href="#Lisp_nn4">Additional Commandline Options </a>
  17 <li><a href="#Lisp_nn5">Generating CFFI bindings</a>
  18 <li><a href="#Lisp_nn6">Generating CFFI bindings for C++ code</a>
  19 <li><a href="#Lisp_nn7">Inserting user code into generated files</a>
  20 </ul>
  21 <li><a href="#Lisp_nn8">CLISP</a>
  22 <ul>
  23 <li><a href="#Lisp_nn9">Additional Commandline Options </a>
  24 <li><a href="#Lisp_nn10">Details on CLISP bindings</a>
  25 </ul>
  26 <li><a href="#Lisp_nn11">UFFI </a>
  27 </ul>
  28 </div>
  29 <!-- INDEX -->
  30
  31
  32
  33 <p>
  34       Common Lisp is a high-level, all-purpose, object-oriented,
  35       dynamic, functional programming language with long history.
  36       Common Lisp is used in many fields, ranging from web development to
  37       finance, and also common in computer science education.
  38       There are more than 9 different implementations of common lisp which
  39       are available, all have different foreign function
  40       interfaces. SWIG currently supports only the Allegro Common
  41       Lisp, Common Foreign Function Interface(CFFI), CLisp and UFFI
  42       foreign function interfaces.
  43 </p>
  44 <H2><a name="Lisp_nn2"></a>22.1 Allegro Common Lisp</H2>
  45
  46
  47 <p>
  48   Allegro Common Lisp support in SWIG has been updated to include
  49   support for both C and C++. You can read about the interface
  50   <a href="Allegrocl.html#Allegrocl_nn1">here</a>
  51 </p>
  52
  53 <H2><a name="Lisp_nn3"></a>22.2 Common Foreign Function Interface(CFFI)</H2>
  54
  55
  56 <p>
  57       CFFI, the Common Foreign Function Interface, is a portable foreign
  58       function interface for ANSI Common Lisp systems, similar in
  59       spirit to UFFI. Unlike UFFI, CFFI requires only a small set of
  60       low-level functionality from the Lisp implementation, such as
  61       calling a foreign function by name, allocating foreign memory,
  62       and dereferencing pointers.
  63 </p>
  64
  65 <p>
  66       To run the cffi module of SWIG requires very little effort, you
  67       just need to run:
  68 </p>
  69 <div class="code"><pre>
  70 swig -cffi -module <i>module-name</i>   <i>file-name</i>
  71
  72 </pre></div>
  73
  74 <p>
  75       But a better was of using all the power of SWIG is to write SWIG
  76       interface files. Below we will explain how to write interface
  77       files and the various things which you can do with them.
  78 </p>
  79
  80 <H3><a name="Lisp_nn4"></a>22.2.1 Additional Commandline Options </H3>
  81
  82
  83 <p>
  84 The following table list the additional commandline options available for the CLISP module. They can also be seen by using:
  85 </p>
  86
  87 <div class="code"><pre>
  88 swig -cffi -help
  89 </pre></div>
  90 <br/>
  91
  92 <table summary="CFFI specific options">
  93 <tr>
  94  <th> CFFI specific options</th>
  95 </tr>
  96
  97 <tr>
  98 <td>-generate-typedef</td>
  99 <td>If this option is given then defctype will be used to generate<br\>
 100       shortcuts according to the typedefs in the input.
 101 </td>
 102 </tr>
 103
 104 <tr>
 105 <td>-[no]cwrap</td>
 106 <td>Turn on or turn off generation of an intermediate C file when<br\>
 107     creating a C interface. By default this is only done for C++ code.
 108 </td>
 109 </tr>
 110
 111 <tr>
 112 <td>-[no]swig-lisp</td>
 113 <td>Turns on or off generation of code for helper lisp macro, functions,
 114       etc. which SWIG uses while generating wrappers. These macros, functions
 115       may still be used by generated wrapper code.
 116 </td>
 117 </tr>
 118
 119 </table>
 120
 121 <H3><a name="Lisp_nn5"></a>22.2.2 Generating CFFI bindings</H3>
 122
 123
 124 As we mentioned earlier the ideal way to use SWIG is to use interface
 125     files. To illustrate the use of it, lets assume that we have a
 126     file named <i>test.h</i> with the following C code:
 127
 128 <div class="code"><pre>
 129 #define y 5
 130 #define x (y &gt;&gt;  1)
 131
 132 typedef int days;
 133
 134 struct bar {
 135   short p, q;
 136     char a, b;
 137     int *z[1000];
 138     struct bar * n;
 139 };
 140
 141 struct   bar * my_struct;
 142
 143 struct foo {
 144     int a;
 145     struct foo * b[100];
 146
 147 };
 148
 149 int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int p);
 150
 151 int func123(div_t * p,int **q[100],int r[][1000][10]);
 152
 153 void lispsort_double (int n, double * array);
 154
 155 enum color { RED, BLUE, GREEN};
 156 </pre></div>
 157
 158 Corresponding to this we will write a simple interface file:
 159 <div class="code"><pre>
 160 %module test
 161
 162 %include "test.h"
 163
 164 </pre></div>
 165
 166 The generated SWIG Code will be:
 167
 168 <div class="targetlang"><pre>
 169 ;;;SWIG wrapper code starts here
 170
 171 (cl:defmacro defanonenum (&amp;body enums)
 172    "Converts anonymous enums to defconstants."
 173   `(cl:progn ,@(cl:loop for value in enums
 174                         for index = 0 then (cl:1+ index)
 175                         when (cl:listp value) do (cl:setf index (cl:second value)
 176                                                           value (cl:first value))
 177                         collect `(cl:defconstant ,value ,index))))
 178
 179 (cl:eval-when (:compile-toplevel :load-toplevel)
 180   (cl:unless (cl:fboundp 'swig-lispify)
 181     (cl:defun swig-lispify (name flag cl:&amp;optional (package cl:*package*))
 182       (cl:labels ((helper (lst last rest cl:&amp;aux (c (cl:car lst)))
 183                     (cl:cond
 184                       ((cl:null lst)
 185                        rest)
 186                       ((cl:upper-case-p c)
 187                        (helper (cl:cdr lst) 'upper
 188                                (cl:case last
 189                                  ((lower digit) (cl:list* c #\- rest))
 190                                  (cl:t (cl:cons c rest)))))
 191                       ((cl:lower-case-p c)
 192                        (helper (cl:cdr lst) 'lower (cl:cons (cl:char-upcase c) rest)))
 193                       ((cl:digit-char-p c)
 194                        (helper (cl:cdr lst) 'digit
 195                                (cl:case last
 196                                  ((upper lower) (cl:list* c #\- rest))
 197                                  (cl:t (cl:cons c rest)))))
 198                       ((cl:char-equal c #\_)
 199                        (helper (cl:cdr lst) '_ (cl:cons #\- rest)))
 200                       (cl:t
 201                        (cl:error "Invalid character: ~A" c)))))
 202         (cl:let ((fix (cl:case flag
 203                         ((constant enumvalue) "+")
 204                         (variable "*")
 205                         (cl:t ""))))
 206           (cl:intern
 207            (cl:concatenate
 208             'cl:string
 209             fix
 210             (cl:nreverse (helper (cl:concatenate 'cl:list name) cl:nil cl:nil))
 211             fix)
 212            package))))))
 213
 214 ;;;SWIG wrapper code ends here
 215
 216
 217 (cl:defconstant y 5)
 218
 219 (cl:defconstant x (cl:ash 5 -1))
 220
 221 (cffi:defcstruct bar
 222         (p :short)
 223         (q :short)
 224         (a :char)
 225         (b :char)
 226         (z :pointer)
 227         (n :pointer))
 228
 229 (cffi:defcvar ("my_struct" my_struct)
 230  :pointer)
 231
 232 (cffi:defcstruct foo
 233         (a :int)
 234         (b :pointer))
 235
 236 (cffi:defcfun ("pointer_func" pointer_func) :int
 237   (ClosureFun :pointer)
 238   (p :int))
 239
 240 (cffi:defcfun ("func123" func123) :int
 241   (p :pointer)
 242   (q :pointer)
 243   (r :pointer))
 244
 245 (cffi:defcfun ("lispsort_double" lispsort_double) :void
 246   (n :int)
 247   (array :pointer))
 248
 249 (cffi:defcenum color
 250         :RED
 251         :BLUE
 252         :GREEN)
 253 </pre></div>
 254
 255 <p>
 256    The <i>SWIG wrapper</i> code refers to the special code which SWIG
 257     may need to use while wrapping C code. You can turn on/off the
 258     generation of this code by using the <i>-[no]swig-lisp</i>
 259     option. You must have noticed that SWIG goes one extra step to
 260     ensure that CFFI does not do automatic lispification of the C
 261     function names. The reason SWIG does this is because quite often
 262     developers want to build a nice CLOS based lispy API, and this one
 263     to one correspondence between C function names and lisp function
 264     name helps.
 265 </p>
 266
 267 <p> Maybe you want to have your own convention for generating lisp
 268       function names for corresponding C function names, or you just
 269       want to lispify the names, also, before we forget you want to
 270       export the generated lisp names. To do this, we will use the
 271       SWIG <a
 272         href="Customization.html#features">feature directive</a>.
 273 Let's edit the interface file such that the C type "div_t*" is changed
 274       to Lisp type ":my-pointer", we lispify all names,
 275       export everything, and do some more stuff.
 276
 277 </p>
 278 <div class="code"><pre>
 279 %module test
 280
 281 %typemap(cin) div_t* ":my-pointer";
 282
 283 %feature("intern_function","1");
 284 %feature("export");
 285
 286 %feature("inline") lispsort_double;
 287
 288 %feature("intern_function", "my-lispify") lispsort_double;
 289 %rename func123 renamed_cool_func;
 290 %ignore "pointer_func";
 291
 292 %include "test.h"
 293
 294 </pre></div>
 295
 296 <p>
 297 The <i>typemap(cin)</i> ensures that for all arguments which are input
 298     to C with the type "div_t*", the ":my-pointer" type be
 299     used. Similarly  <i>typemap(cout)</i> are used for all types which
 300     are returned from C.
 301 </p>
 302 <p>
 303 The feature <i>intern_function</i> ensures that all C names are
 304       interned using the <b>swig-lispify</b> function. The "1" given
 305       to the feature is optional. The use of feature like
 306       <i>%feature("intern_function","1");</i> globally enables
 307       interning for everything. If you want to target a single
 308       function, or declaration then use the targeted version of
 309       feature, <i>%feature("intern_function", "my-lispify")
 310         lispsort_double;</i>, here we are using an additional feature
 311       which allows us to use our lispify function.
 312 </p>
 313 <p>The <i>export</i> feature allows us to export the symbols. The <i>inline</i>
 314       feature declaims the declared function as inline. The <i>rename</i>
 315       directive allows us to change the name(it is useful when
 316       generating C wrapper code for handling overloaded
 317       functions). The <i>ignore</i> directive ignores a certain
 318       declaration.
 319 </p>
 320 <p>There are several other things which are possible, to see some
 321       example of usage of SWIG look at the Lispbuilder and wxCL
 322       projects. The generated code with 'noswig-lisp' option is:
 323 </p>
 324
 325 <div class="targetlang"><pre>
 326 (cl:defconstant #.(swig-lispify "y" 'constant) 5)
 327
 328 (cl:export '#.(swig-lispify "y" 'constant))
 329
 330 (cl:defconstant #.(swig-lispify "x" 'constant) (cl:ash 5 -1))
 331
 332 (cl:export '#.(swig-lispify "x" 'constant))
 333
 334 (cffi:defcstruct #.(swig-lispify "bar" 'classname)
 335         (#.(swig-lispify "p" 'slotname) :short)
 336         (#.(swig-lispify "q" 'slotname) :short)
 337         (#.(swig-lispify "a" 'slotname) :char)
 338         (#.(swig-lispify "b" 'slotname) :char)
 339         (#.(swig-lispify "z" 'slotname) :pointer)
 340         (#.(swig-lispify "n" 'slotname) :pointer))
 341
 342 (cl:export '#.(swig-lispify "bar" 'classname))
 343
 344 (cl:export '#.(swig-lispify "p" 'slotname))
 345
 346 (cl:export '#.(swig-lispify "q" 'slotname))
 347
 348 (cl:export '#.(swig-lispify "a" 'slotname))
 349
 350 (cl:export '#.(swig-lispify "b" 'slotname))
 351
 352 (cl:export '#.(swig-lispify "z" 'slotname))
 353
 354 (cl:export '#.(swig-lispify "n" 'slotname))
 355
 356 (cffi:defcvar ("my_struct" #.(swig-lispify "my_struct" 'variable))
 357  :pointer)
 358
 359 (cl:export '#.(swig-lispify "my_struct" 'variable))
 360
 361 (cffi:defcstruct #.(swig-lispify "foo" 'classname)
 362         (#.(swig-lispify "a" 'slotname) :int)
 363         (#.(swig-lispify "b" 'slotname) :pointer))
 364
 365 (cl:export '#.(swig-lispify "foo" 'classname))
 366
 367 (cl:export '#.(swig-lispify "a" 'slotname))
 368
 369 (cl:export '#.(swig-lispify "b" 'slotname))
 370
 371 (cffi:defcfun ("renamed_cool_func" #.(swig-lispify "renamed_cool_func" 'function)) :int
 372   (p :my-pointer)
 373   (q :pointer)
 374   (r :pointer))
 375
 376 (cl:export '#.(swig-lispify "renamed_cool_func" 'function))
 377
 378 (cl:declaim (cl:inline #.(my-lispify "lispsort_double" 'function)))
 379
 380 (cffi:defcfun ("lispsort_double" #.(my-lispify "lispsort_double" 'function)) :void
 381   (n :int)
 382   (array :pointer))
 383
 384 (cl:export '#.(my-lispify "lispsort_double" 'function))
 385
 386 (cffi:defcenum #.(swig-lispify "color" 'enumname)
 387         #.(swig-lispify "RED" 'enumvalue :keyword)
 388         #.(swig-lispify "BLUE" 'enumvalue :keyword)
 389         #.(swig-lispify "GREEN" 'enumvalue :keyword))
 390
 391 (cl:export '#.(swig-lispify "color" 'enumname))
 392
 393 </pre></div>
 394
 395 <H3><a name="Lisp_nn6"></a>22.2.3 Generating CFFI bindings for C++ code</H3>
 396
 397
 398 <p>This feature to SWIG (for CFFI) is very new and still far from
 399     complete. Pitch in with your patches, bug reports and feature
 400     requests to improve it.
 401 </p>
 402 <p> Generating bindings for C++ code, requires <i>-c++</i> option to be
 403       present and it first generates C binding which will wrap the C++
 404       code, and then generates the
 405       corresponding CFFI wrapper code. In the generated C wrapper
 406       code, you will often want to put your own C code, such as the
 407       code to include various files. This can be done by making use of
 408       "%{" and "%}" as shown below.
 409 </p>
 410 <div class="code"><pre>
 411 %{
 412  #include "Test/test.h"
 413 %}
 414 </pre></div>
 415 <p>
 416 Also, while parsing the C++ file and generating C wrapper code SWIG
 417     may need to be able to understand various symbols used in other
 418     header files. To help SWIG in doing this while ensuring that
 419     wrapper code is generated for the target file, use the "import"
 420     directive. The "include" directive specifies the target file for
 421     which wrapper code will be generated.
 422 </p>
 423 <div class="code"><pre>
 424
 425 %import "ancillary/header.h"
 426
 427 %include "target/header.h"
 428
 429 </pre></div>
 430 Various features which were available for C headers can also be used
 431     here. The target header which we are going to use here is:
 432 <div class="code"><pre>
 433 namespace OpenDemo {
 434   class Test
 435     {
 436     public:
 437         float x;
 438         // constructors
 439         Test (void) {x = 0;}
 440         Test (float X) {x = X;}
 441
 442         // vector addition
 443         Test operator+ (const Test&amp; v) const {return Test (x+v.x);}
 444
 445       // length squared
 446         float lengthSquared (void) const {return this-&gt;dot (*this);}
 447
 448         static float distance (const Test&amp; a, const Test&amp; b){return(a-b).length();}
 449
 450         inline Test parallelComponent (const Test&amp; unitBasis) const {
 451           return unitBasis * projection;
 452         }
 453
 454         Test setYtoZero (void) const {return Test (this-&gt;x);}
 455
 456         static const Test zero;
 457     };
 458
 459
 460    inline Test operator* (float s, const Test&amp; v) {return v*s;}
 461
 462
 463     inline std::ostream&amp; operator&lt;&lt; (std::ostream&amp; o, const Test&amp; v)
 464     {
 465         return o &lt;&lt; "(" &lt;&lt; v.x &lt;&lt; ")";
 466     }
 467
 468
 469     inline Test RandomUnitVectorOnXZPlane (void)
 470     {
 471         return RandomVectorInUnitRadiusSphere().setYtoZero().normalize();
 472     }
 473 }
 474 </pre></div>
 475 <p>The interface used is: </p>
 476 <div class="code"><pre>
 477 %module test
 478 %include "test.cpp"
 479 </pre></div>
 480
 481 SWIG generates 3 files, the first one is a C wrap which we don't show,
 482     the second is the plain CFFI wrapper which is as shown below:
 483 <div class="targetlang"><pre>
 484 (cffi:defcfun ("_wrap_Test_x_set" Test_x_set) :void
 485   (self :pointer)
 486   (x :float))
 487
 488 (cffi:defcfun ("_wrap_Test_x_get" Test_x_get) :float
 489   (self :pointer))
 490
 491 (cffi:defcfun ("_wrap_new_Test__SWIG_0" new_Test) :pointer)
 492
 493 (cffi:defcfun ("_wrap_new_Test__SWIG_1" new_Test) :pointer
 494   (X :float))
 495
 496 (cffi:defcfun ("_wrap_Test___add__" Test___add__) :pointer
 497   (self :pointer)
 498   (v :pointer))
 499
 500 (cffi:defcfun ("_wrap_Test_lengthSquared" Test_lengthSquared) :float
 501   (self :pointer))
 502
 503 (cffi:defcfun ("_wrap_Test_distance" Test_distance) :float
 504   (a :pointer)
 505   (b :pointer))
 506
 507 (cffi:defcfun ("_wrap_Test_parallelComponent" Test_parallelComponent) :pointer
 508   (self :pointer)
 509   (unitBasis :pointer))
 510
 511 (cffi:defcfun ("_wrap_Test_setYtoZero" Test_setYtoZero) :pointer
 512   (self :pointer))
 513
 514 (cffi:defcvar ("Test_zero" Test_zero)
 515  :pointer)
 516
 517 (cffi:defcfun ("_wrap_delete_Test" delete_Test) :void
 518   (self :pointer))
 519
 520 (cffi:defcfun ("_wrap___mul__" __mul__) :pointer
 521   (s :float)
 522   (v :pointer))
 523
 524 (cffi:defcfun ("_wrap___lshift__" __lshift__) :pointer
 525   (o :pointer)
 526   (v :pointer))
 527
 528 (cffi:defcfun ("_wrap_RandomUnitVectorOnXZPlane" RandomUnitVectorOnXZPlane) :pointer)
 529 </pre></div>
 530
 531 The output is pretty good but it fails in disambiguating overloaded
 532     functions such as the constructor, in this case. One way of
 533     resolving this problem is to make the interface use the rename
 534     directiv, but hopefully there are better solutions.
 535  In addition SWIG also generates, a CLOS file
 536
 537
 538 <div class="targetlang"><pre>
 539 (clos:defclass test()
 540   ((ff :reader ff-pointer)))
 541
 542 (clos:defmethod (cl:setf x) (arg0 (obj test))
 543   (Test_x_set (ff-pointer obj) arg0))
 544
 545 (clos:defmethod x ((obj test))
 546   (Test_x_get (ff-pointer obj)))
 547
 548 (cl:shadow "+")
 549 (clos:defmethod + ((obj test) (self test) (v test))
 550   (Test___add__ (ff-pointer obj) (ff-pointer self) (ff-pointer v)))
 551
 552 (clos:defmethod length-squared ((obj test) (self test))
 553   (Test_lengthSquared (ff-pointer obj) (ff-pointer self)))
 554
 555 (clos:defmethod parallel-component ((obj test) (self test) (unitBasis test))
 556   (Test_parallelComponent (ff-pointer obj) (ff-pointer self) (ff-pointer unitBasis)))
 557
 558 (clos:defmethod set-yto-zero ((obj test) (self test))
 559   (Test_setYtoZero (ff-pointer obj) (ff-pointer self)))
 560 </pre></div>
 561
 562 <p>I agree that the CFFI C++ module needs lot more work. But I hope it
 563     provides a starting point, on which you can base your work of
 564     importing C++ libraries to Lisp.
 565 </p>
 566 <p>
 567 If you have any questions, suggestions, patches, etc., related to CFFI
 568       module feel free to contact us on the SWIG mailing list, and
 569       also please add a "[CFFI]" tag in the subject line.
 570
 571 <H3><a name="Lisp_nn7"></a>22.2.4 Inserting user code into generated files</H3>
 572
 573
 574 <p>
 575 It is often necessary to <a href="SWIG.html#SWIG_nn40">include user-defined code</a>
 576 into the automatically generated interface files. For example, when building
 577 a C++ interface, example_wrap.cxx will likely not compile unless
 578 you add a <tt>#include "header.h"</tt> directive. This can be done
 579 using the SWIG <tt>%insert(section) %{ ...code... %}</tt> directive:
 580 </p>
 581
 582 <div class="code">
 583 <pre>
 584 %module example
 585
 586 %{
 587 #include "header.h"
 588 %}
 589
 590 %include "header.h"
 591
 592 int fact(int n);
 593 </pre>
 594 </div>
 595
 596 <p>
 597 Additional sections have been added for inserting into the
 598 generated lisp interface file:
 599 </p>
 600 <ul>
 601   <li><tt>lisphead</tt> - inserts before type declarations</li>
 602   <li><tt>swiglisp</tt> - inserts after type declarations according to
 603     where it appears in the .i file</li>
 604 </ul>
 605 <p>
 606 Note that the block <tt>%{ ... %}</tt> is effectively a shortcut for
 607 <tt>%insert("header") %{ ... %}</tt>.
 608 </p>
 609
 610
 611 <H2><a name="Lisp_nn8"></a>22.3 CLISP</H2>
 612
 613
 614 <p>
 615 <a href="http://clisp.cons.org">CLISP</a> is a feature-loaded
 616       implementation of common lisp which is portable across most of the
 617       operating system environments and hardware. CLISP includes an
 618       interpreter, a compiler, a debugger, CLOS, MOP, a foreign
 619       language interface, i18n, regular expressions, a socket
 620       interface, and more. An X11 interface is available through CLX,
 621       Garnet and CLUE/CLIO. Command line editing is provided by
 622       readline. CLISP runs Maxima, ACL2 and many other Common Lisp
 623       packages.
 624 </p>
 625 <p>
 626       To run the clisp module of SWIG requires very little effort, you
 627       just need to execute:
 628 </p>
 629 <div class="code"><pre>
 630 swig -clisp -module <i>module-name</i>   <i>file-name</i>
 631
 632 </pre></div>
 633
 634 <p>
 635     Because of the high level nature of the CLISP FFI, the bindings
 636     generated by SWIG may not be absolutely correct, and you may need
 637     to modify them. The good thing is that you don't need to complex
 638     interface file for the CLISP module. The CLISP module tries to
 639     produce code which is both human readable and easily modifyable.
 640 </p>
 641 <H3><a name="Lisp_nn9"></a>22.3.1 Additional Commandline Options </H3>
 642
 643
 644 <p>
 645 The following table list the additional commandline options available for the CLISP module. They can also be seen by using:
 646 </p>
 647
 648 <div class="code"><pre>
 649 swig -clisp -help
 650 </pre></div>
 651 <br/>
 652 <table summary="CLISP specific options">
 653 <tr>
 654 <th>CLISP specific options</th>
 655 </tr>
 656
 657 <tr>
 658 <td>-extern-all</td>
 659 <td>If this option is given then clisp definitions for all the functions<br/>
 660 and global variables will be created otherwise only definitions for<br/>
 661             externed functions and variables are created.
 662 </td>
 663 </tr>
 664
 665 <tr>
 666 <td>-generate-typedef</td>
 667 <td>If this option is given then def-c-type will be used to generate<br/>
 668             shortcuts according to the typedefs in the input.
 669 </td>
 670 </tr>
 671
 672 </table>
 673
 674 <H3><a name="Lisp_nn10"></a>22.3.2 Details on CLISP bindings</H3>
 675
 676
 677 <p>
 678 As mentioned earlier the CLISP bindings generated by SWIG may need
 679         some modifications. The clisp module creates a lisp file with
 680         the same name as the module name. This
 681         lisp file contains a 'defpackage' declaration, with the
 682         package name same as the module name. This package uses the
 683         'common-lisp' and 'ffi' packages. Also, package exports all
 684         the functions, structures and variables for which an ffi
 685         binding was generated.<br/>
 686      After generating the defpackage statement, the clisp module also
 687         sets the default language.
 688
 689 <div class="targetlang"><pre>
 690 (defpackage :test
 691     (:use :common-lisp :ffi)
 692   (:export
 693    :make-bar
 694    :bar-x
 695    :bar-y
 696    :bar-a
 697    :bar-b
 698    :bar-z
 699    :bar-n
 700    :pointer_func
 701    :func123
 702    :make-cfunr
 703    :lispsort_double
 704    :test123))
 705
 706 (in-package :test)
 707
 708 (default-foreign-language :stdc)
 709 </pre></div>
 710 <p>
 711 The ffi wrappers for functions and variables are generated as shown
 712       below. When functions have arguments of type "double * array",
 713       SWIG doesn't knows whether it is an 'out' argument or it is
 714       an array which will be passed, so SWIG plays it safe by
 715       declaring it as an '(array (ffi:c-ptr DOUBLE-FLOAT))'. For
 716       arguments of type "int **z[100]" where SWIG has more
 717       information, i.e., it knows that 'z' is an array of pointers to
 718       pointers of integers, SWIG defines it to be '(z (ffi:c-ptr
 719       (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))'
 720 </p>
 721 <div class="code"><pre>
 722 extern "C" {
 723 int pointer_func(void (*ClosureFun)( void* _fun, void* _data, void* _evt ), int y);
 724
 725 int func123(div_t * x,int **z[100],int y[][1000][10]);
 726
 727 void lispsort_double (int n, double * array);
 728
 729 void test123(float x , double y);
 730
 731 }
 732 </pre></div>
 733 <div class="targetlang"><pre>
 734 (ffi:def-call-out pointer_func
 735     (:name "pointer_func")
 736   (:arguments (ClosureFun (ffi:c-function (:arguments (arg0 (ffi:c-pointer NIL))
 737                                                       (arg1 (ffi:c-pointer NIL))
 738                                                       (arg2 (ffi:c-pointer NIL)))
 739                                           (:return-type NIL)))
 740               (y ffi:int))
 741   (:return-type ffi:int)
 742   (:library +library-name+))
 743
 744 (ffi:def-call-out func123
 745     (:name "func123")
 746   (:arguments (x (ffi:c-pointer div_t))
 747               (z (ffi:c-ptr (ffi:c-array (ffi:c-ptr (ffi:c-ptr ffi:int)) 100)))
 748               (y (ffi:c-ptr (ffi:c-ptr (ffi:c-array ffi:int (1000 10))))))
 749   (:return-type ffi:int)
 750   (:library +library-name+))
 751
 752
 753 (ffi:def-call-out lispsort_double
 754     (:name "lispsort_double")
 755   (:arguments (n ffi:int)
 756               (array (ffi:c-ptr DOUBLE-FLOAT)))
 757   (:return-type NIL)
 758   (:library +library-name+))
 759
 760 (ffi:def-call-out test123
 761     (:name "test")
 762   (:arguments (x SINGLE-FLOAT)
 763               (y DOUBLE-FLOAT))
 764   (:return-type NIL)
 765   (:library +library-name+))
 766
 767 </pre></div>
 768
 769 <p>
 770 The module also handles strutcures and #define constants as shown
 771       below. SWIG automatically adds the constructors and accessors
 772     created for the struct to the list of symbols exported by the
 773       package.
 774 </p>
 775 <div class="code"><pre>
 776 struct bar {
 777     short x, y;
 778     char a, b;
 779     int *z[1000];
 780     struct bar * n;
 781 };
 782
 783 #define max 1000
 784 </pre></div>
 785 <div class="targetlang"><pre>
 786 (ffi:def-c-struct bar
 787     (x :type ffi:short)
 788   (y :type ffi:short)
 789   (a :type character)
 790   (b :type character)
 791   (z :type (ffi:c-array (ffi:c-ptr ffi:int) 1000))
 792   (n :type (ffi:c-pointer bar)))
 793
 794 (defconstant max 1000)
 795
 796 </pre></div>
 797
 798 <H2><a name="Lisp_nn11"></a>22.4 UFFI </H2>
 799
 800
 801 </body>
 802 </html>