Doc/Manual/Preprocessor.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>SWIG Preprocessor</title>
   5 <link rel="stylesheet" type="text/css" href="style.css">
   6 </head>
   7
   8 <body bgcolor="#ffffff">
   9 <H1><a name="Preprocessor"></a>7 Preprocessing</H1>
  10 <!-- INDEX -->
  11 <div class="sectiontoc">
  12 <ul>
  13 <li><a href="#Preprocessor_nn2">File inclusion</a>
  14 <li><a href="#Preprocessor_nn3">File imports</a>
  15 <li><a href="#Preprocessor_condition_compilation">Conditional Compilation</a>
  16 <li><a href="#Preprocessor_nn5">Macro Expansion</a>
  17 <li><a href="#Preprocessor_nn6">SWIG Macros</a>
  18 <li><a href="#Preprocessor_nn7">C99 and GNU Extensions</a>
  19 <li><a href="#Preprocessor_nn8">Preprocessing and %{ ... %} &amp; " ... " delimiters</a>
  20 <li><a href="#Preprocessor_nn9">Preprocessing and { ... } delimiters</a>
  21 <li><a href="#Preprocessor_typemap_delimiters">Preprocessor and Typemaps</a>
  22 <li><a href="#Preprocessor_nn10">Viewing preprocessor output</a>
  23 <li><a href="#Preprocessor_warning_error">The #error and #warning directives</a>
  24 </ul>
  25 </div>
  26 <!-- INDEX -->
  27
  28
  29
  30 <p>
  31 SWIG includes its own enhanced version of the C preprocessor.  The preprocessor
  32 supports the standard preprocessor directives and macro expansion rules.
  33 However, a number of modifications and enhancements have been made.  This
  34 chapter describes some of these modifications.
  35 </p>
  36
  37 <H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2>
  38
  39
  40 <p>
  41 To include another file into a SWIG interface, use the <tt>%include</tt> directive
  42 like this:
  43 </p>
  44
  45 <div class="code">
  46 <pre>
  47 %include "pointer.i"
  48 </pre>
  49 </div>
  50
  51 <p>
  52 Unlike, <tt>#include</tt>, <tt>%include</tt> includes each file once (and will not
  53 reload the file on subsequent <tt>%include</tt> declarations).  Therefore, it
  54 is not necessary to use include-guards in SWIG interfaces.
  55 </p>
  56
  57 <p>
  58 By default, the <tt>#include</tt> is ignored unless you run SWIG with the
  59 <tt>-includeall</tt> option.   The reason for ignoring traditional includes
  60 is that you often don't want SWIG to try and wrap everything included
  61 in standard header system headers and auxiliary files.
  62
  63 <H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2>
  64
  65
  66 <p>
  67 SWIG provides another file inclusion directive with the <tt>%import</tt> directive.
  68 For example:
  69 </p>
  70
  71 <div class="code">
  72 <pre>
  73 %import "foo.i"
  74 </pre>
  75 </div>
  76
  77 <p>
  78 The purpose of <tt>%import</tt> is to collect certain information from another
  79 SWIG interface file or a header file without actually generating any wrapper code.
  80 Such information generally includes type declarations (e.g., <tt>typedef</tt>) as well as
  81 C++ classes that might be used as base-classes for class declarations in the interface.
  82 The use of <tt>%import</tt> is also important when SWIG is used to generate
  83 extensions as a collection of related modules.   This is an advanced topic and is described
  84 in later in the <a href="Modules.html">Working with Modules</a> chapter.
  85 </p>
  86
  87 <P>
  88 The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> statements
  89 as imports.    This might be useful if you want to extract type definitions from system
  90 header files without generating any wrappers.
  91
  92 <H2><a name="Preprocessor_condition_compilation"></a>7.3 Conditional Compilation</H2>
  93
  94
  95 <p>
  96 SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>,
  97 <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally
  98 include parts of an interface.  The following symbols are predefined
  99 by SWIG when it is parsing the interface:
 100 </p>
 101
 102 <div class="code"><pre>
 103 SWIG                            Always defined when SWIG is processing a file
 104 SWIGIMPORTED                    Defined when SWIG is importing a file with <tt>%import</tt>
 105 SWIGMAC                         Defined when running SWIG on the Macintosh
 106 SWIGWIN                         Defined when running SWIG under Windows
 107 SWIG_VERSION                    Hexadecimal number containing SWIG version,
 108                                 such as 0x010311 (corresponding to SWIG-1.3.11).
 109
 110 SWIGALLEGROCL                   Defined when using Allegro CL
 111 SWIGCFFI                        Defined when using CFFI
 112 SWIGCHICKEN                     Defined when using CHICKEN
 113 SWIGCLISP                       Defined when using CLISP
 114 SWIGCSHARP                      Defined when using C#
 115 SWIGGUILE                       Defined when using Guile
 116 SWIGJAVA                        Defined when using Java
 117 SWIGLUA                         Defined when using Lua
 118 SWIGMODULA3                     Defined when using Modula-3
 119 SWIGMZSCHEME                    Defined when using Mzscheme
 120 SWIGOCAML                       Defined when using Ocaml
 121 SWIGOCTAVE                      Defined when using Octave
 122 SWIGPERL                        Defined when using Perl
 123 SWIGPHP                         Defined when using PHP
 124 SWIGPIKE                        Defined when using Pike
 125 SWIGPYTHON                      Defined when using Python
 126 SWIGR                           Defined when using R
 127 SWIGRUBY                        Defined when using Ruby
 128 SWIGSEXP                        Defined when using S-expressions
 129 SWIGTCL                         Defined when using Tcl
 130 SWIGXML                         Defined when using XML
 131 </pre></div>
 132
 133 <p>
 134 In addition, SWIG defines the following set of standard C/C++ macros:
 135 </p>
 136
 137 <div class="code">
 138 <pre>
 139 __LINE__                        Current line number
 140 __FILE__                        Current file name
 141 __STDC__                        Defined to indicate ANSI C
 142 __cplusplus                     Defined when -c++ option used
 143 </pre>
 144 </div>
 145
 146 <p>
 147 Interface files can look at these symbols as necessary to change the
 148 way in which an interface is generated or to mix SWIG directives with
 149 C code. These symbols are also defined within the C code generated by
 150 SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined
 151 within the SWIG compiler).
 152 </p>
 153
 154 <H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2>
 155
 156
 157 <p>
 158 Traditional preprocessor macros can be used in SWIG interfaces.  Be aware that the <tt>#define</tt> statement
 159 is also used to try and detect constants.  Therefore, if you have something like this in your file,
 160 </p>
 161
 162 <div class="code">
 163 <pre>
 164 #ifndef _FOO_H 1
 165 #define _FOO_H 1
 166 ...
 167 #endif
 168 </pre>
 169 </div>
 170
 171 <p>
 172 you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
 173 </p>
 174
 175 <p>
 176 More complex macros can be defined in the standard way. For example:
 177 </p>
 178
 179 <div class="code">
 180 <pre>
 181 #define EXTERN extern
 182 #ifdef __STDC__
 183 #define _ANSI(args)   (args)
 184 #else
 185 #define _ANSI(args) ()
 186 #endif
 187 </pre>
 188 </div>
 189
 190 <p>
 191 The following operators can appear in macro definitions:
 192 </p>
 193
 194 <ul>
 195 <li><tt>#x</tt><br>
 196 Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x").
 197 </li>
 198
 199 <li><tt>x ## y</tt><br>
 200 Concatenates x and y together to form <tt>xy</tt>.
 201 </li>
 202
 203 <li><tt>`x`</tt><br>
 204 If <tt>x</tt> is a string surrounded by double quotes, do nothing.  Otherwise, turn into a string
 205 like <tt>#x</tt>.  This is a non-standard SWIG extension.
 206 </li>
 207 </ul>
 208
 209 <H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2>
 210
 211
 212 <p>
 213 SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives.
 214 For example:
 215 </p>
 216
 217 <div class="code">
 218 <pre>
 219 %define ARRAYHELPER(type,name)
 220 %inline %{
 221 type *new_ ## name (int nitems) {
 222    return (type *) malloc(sizeof(type)*nitems);
 223 }
 224 void delete_ ## name(type *t) {
 225    free(t);
 226 }
 227 type name ## _get(type *t, int index) {
 228    return t[index];
 229 }
 230 void name ## _set(type *t, int index, type val) {
 231    t[index] = val;
 232 }
 233 %}
 234 %enddef
 235
 236 ARRAYHELPER(int, IntArray)
 237 ARRAYHELPER(double, DoubleArray)
 238 </pre>
 239 </div>
 240
 241 <p>
 242 The primary purpose of <tt>%define</tt> is to define large macros of code.  Unlike normal C preprocessor
 243 macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition
 244 extends to the first occurrence of <tt>%enddef</tt>.    Furthermore, when such macros are expanded,
 245 they are reparsed through the C preprocessor.  Thus, SWIG macros can contain all other preprocessor
 246 directives except for nested <tt>%define</tt> statements.
 247 </p>
 248
 249 <p>
 250 The SWIG macro capability is a very quick and easy way to generate large amounts of code.  In fact,
 251 many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template
 252 support).
 253 </p>
 254
 255 <H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2>
 256
 257
 258 <p>
 259 SWIG-1.3.12 and newer releases support variadic preprocessor macros.  For example:
 260 </p>
 261
 262 <div class="code">
 263 <pre>
 264 #define DEBUGF(fmt,...)   fprintf(stderr,fmt,__VA_ARGS__)
 265 </pre>
 266 </div>
 267
 268 <p>
 269 When used, any extra arguments to <tt>...</tt> are placed into the
 270 special variable <tt>__VA_ARGS__</tt>.   This also works with special SWIG
 271 macros defined using <tt>%define</tt>.
 272 </p>
 273
 274 <p>
 275 SWIG allows a variable number of arguments to be empty.  However, this often results
 276 in an extra comma (,) and syntax error in the resulting expansion. For example:
 277 </p>
 278
 279 <div class="code">
 280 <pre>
 281 DEBUGF("hello");   --&gt; fprintf(stderr,"hello",);
 282 </pre>
 283 </div>
 284
 285 <p>
 286 To get rid of the extra comma, use <tt>##</tt> like this:
 287 </p>
 288
 289 <div class="code">
 290 <pre>
 291 #define DEBUGF(fmt,...)   fprintf(stderr,fmt, ##__VA_ARGS__)
 292 </pre>
 293 </div>
 294
 295 <p>
 296 SWIG also supports GNU-style variadic macros.    For example:
 297 </p>
 298
 299 <div class="code">
 300 <pre>
 301 #define DEBUGF(fmt, args...)  fprintf(stdout,fmt,args)
 302 </pre>
 303 </div>
 304
 305 <p>
 306 <b>Comment:</b> It's not entirely clear how variadic macros might be useful to
 307 interface building.   However, they are used internally to implement a number of
 308 SWIG directives and are provided to make SWIG more compatible with C99 code.
 309 </p>
 310
 311 <H2><a name="Preprocessor_nn8"></a>7.7 Preprocessing and %{ ... %} &amp; " ... " delimiters</H2>
 312
 313
 314 <p>
 315 The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}.  Therefore,
 316 if you write code like this,
 317 </p>
 318
 319 <div class="code">
 320 <pre>
 321 %{
 322 #ifdef NEED_BLAH
 323 int blah() {
 324    ...
 325 }
 326 #endif
 327 %}
 328 </pre>
 329 </div>
 330
 331 <p>
 332 the contents of the <tt>%{ ... %}</tt> block are copied without
 333 modification to the output (including all preprocessor directives).
 334 </p>
 335
 336 <H2><a name="Preprocessor_nn9"></a>7.8 Preprocessing and { ... } delimiters</H2>
 337
 338
 339 <p>
 340 SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>.  However,
 341 sometimes it is desirable to make a preprocessor directive pass through to the output
 342 file.  For example:
 343 </p>
 344
 345 <div class="code">
 346 <pre>
 347 %extend Foo {
 348    void bar() {
 349       #ifdef DEBUG
 350        printf("I'm in bar\n");
 351       #endif
 352    }
 353 }
 354 </pre>
 355 </div>
 356
 357 <p>
 358 By default, SWIG will interpret the <tt>#ifdef DEBUG</tt> statement.   However, if you really wanted that code
 359 to actually go into the wrapper file, prefix the preprocessor directives with <tt>%</tt> like this:
 360 </p>
 361
 362 <div class="code">
 363 <pre>
 364 %extend Foo {
 365    void bar() {
 366       %#ifdef DEBUG
 367        printf("I'm in bar\n");
 368       %#endif
 369    }
 370 }
 371 </pre>
 372 </div>
 373
 374 <p>
 375 SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
 376 </p>
 377
 378 <H2><a name="Preprocessor_typemap_delimiters"></a>7.9 Preprocessor and Typemaps</H2>
 379
 380
 381 <p>
 382 <a href="Typemaps.html">Typemaps</a> support a special attribute called <tt>noblock</tt> where the { ... } delimiters can be used,
 383 but the delimiters are not actually generated into the code.
 384 The effect is then similar to using "" or %{ %} delimiters but the code <b>is</b> run through the preprocessor. For example:
 385 </p>
 386
 387 <div class="code">
 388 <pre>
 389 #define SWIG_macro(CAST) (CAST)$input
 390 %typemap(in) Int {$1= SWIG_macro(int);}
 391 </pre>
 392 </div>
 393
 394 <p>
 395 might generate
 396 </p>
 397
 398 <div class="code">
 399 <pre>
 400   {
 401     arg1=(int)jarg1;
 402   }
 403 </pre>
 404 </div>
 405
 406 <p>
 407 whereas
 408 </p>
 409
 410 <div class="code">
 411 <pre>
 412 #define SWIG_macro(CAST) (CAST)$input
 413 %typemap(in,noblock=1) Int {$1= SWIG_macro(int);}
 414 </pre>
 415 </div>
 416
 417 <p>
 418 might generate
 419 </p>
 420
 421 <div class="code">
 422 <pre>
 423   arg1=(int)jarg1;
 424 </pre>
 425 </div>
 426
 427 <p>
 428 and
 429 </p>
 430
 431 <div class="code">
 432 <pre>
 433 #define SWIG_macro(CAST) (CAST)$input
 434 %typemap(in) Int %{$1=SWIG_macro(int);%}
 435 </pre>
 436 </div>
 437
 438 <p>
 439 would generate
 440 </p>
 441
 442 <div class="code">
 443 <pre>
 444   arg1=SWIG_macro(int);
 445 </pre>
 446 </div>
 447
 448
 449 <H2><a name="Preprocessor_nn10"></a>7.10 Viewing preprocessor output</H2>
 450
 451
 452 <p>
 453 Like many compilers, SWIG supports a <tt>-E</tt> command line option to display the output from the preprocessor.
 454 When the <tt>-E</tt> switch is used, SWIG will not generate any wrappers.
 455 Instead the results after the preprocessor has run are displayed.
 456 This might be useful as an aid to debugging and viewing the results of macro expansions.
 457 </p>
 458
 459 <H2><a name="Preprocessor_warning_error"></a>7.11 The #error and #warning directives</H2>
 460
 461
 462 <p>
 463 SWIG supports the commonly used <tt>#warning</tt> and <tt>#error</tt> preprocessor directives.
 464 The <tt>#warning</tt> directive will cause SWIG to issue a warning then continue processing.
 465 The <tt>#error</tt> directive will cause SWIG to exit with a fatal error.
 466 Example usage:
 467 </p>
 468
 469 <div class="code">
 470 <pre>
 471 #error "This is a fatal error message"
 472 #warning "This is a warning message"
 473 </pre>
 474 </div>
 475
 476 <p>
 477 The <tt>#error</tt> behaviour can be made to work like <tt>#warning</tt> if the <tt>-cpperraswarn</tt>
 478 commandline option is used. Alternatively, the <tt>#pragma</tt> directive can be used to the same effect, for example:
 479 </p>
 480
 481 <div class="code">
 482 <pre>
 483   /* Modified behaviour: #error does not cause SWIG to exit with error */
 484   #pragma SWIG cpperraswarn=1
 485   /* Normal behaviour: #error does cause SWIG to exit with error */
 486   #pragma SWIG cpperraswarn=0
 487 </pre>
 488 </div>
 489
 490 </body>
 491 </html>