1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>SWIG Preprocessor</title>
5 <link rel="stylesheet" type="text/css" href="style.css">
8 <body bgcolor="#ffffff">
9 <H1><a name="Preprocessor"></a>7 Preprocessing</H1>
11 <div class="sectiontoc">
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 %{ ... %} & " ... " 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>
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.
37 <H2><a name="Preprocessor_nn2"></a>7.1 File inclusion</H2>
41 To include another file into a SWIG interface, use the <tt>%include</tt> directive
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.
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.
63 <H2><a name="Preprocessor_nn3"></a>7.2 File imports</H2>
67 SWIG provides another file inclusion directive with the <tt>%import</tt> directive.
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.
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.
92 <H2><a name="Preprocessor_condition_compilation"></a>7.3 Conditional Compilation</H2>
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:
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).
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
134 In addition, SWIG defines the following set of standard C/C++ macros:
139 __LINE__ Current line number
140 __FILE__ Current file name
141 __STDC__ Defined to indicate ANSI C
142 __cplusplus Defined when -c++ option used
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).
154 <H2><a name="Preprocessor_nn5"></a>7.4 Macro Expansion</H2>
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,
172 you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
176 More complex macros can be defined in the standard way. For example:
181 #define EXTERN extern
183 #define _ANSI(args) (args)
185 #define _ANSI(args) ()
191 The following operators can appear in macro definitions:
196 Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x").
199 <li><tt>x ## y</tt><br>
200 Concatenates x and y together to form <tt>xy</tt>.
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.
209 <H2><a name="Preprocessor_nn6"></a>7.5 SWIG Macros</H2>
213 SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives.
219 %define ARRAYHELPER(type,name)
221 type *new_ ## name (int nitems) {
222 return (type *) malloc(sizeof(type)*nitems);
224 void delete_ ## name(type *t) {
227 type name ## _get(type *t, int index) {
230 void name ## _set(type *t, int index, type val) {
236 ARRAYHELPER(int, IntArray)
237 ARRAYHELPER(double, DoubleArray)
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.
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
255 <H2><a name="Preprocessor_nn7"></a>7.6 C99 and GNU Extensions</H2>
259 SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example:
264 #define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__)
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>.
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:
281 DEBUGF("hello"); --> fprintf(stderr,"hello",);
286 To get rid of the extra comma, use <tt>##</tt> like this:
291 #define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__)
296 SWIG also supports GNU-style variadic macros. For example:
301 #define DEBUGF(fmt, args...) fprintf(stdout,fmt,args)
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.
311 <H2><a name="Preprocessor_nn8"></a>7.7 Preprocessing and %{ ... %} & " ... " delimiters</H2>
315 The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore,
316 if you write code like this,
332 the contents of the <tt>%{ ... %}</tt> block are copied without
333 modification to the output (including all preprocessor directives).
336 <H2><a name="Preprocessor_nn9"></a>7.8 Preprocessing and { ... } delimiters</H2>
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
350 printf("I'm in bar\n");
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:
367 printf("I'm in bar\n");
375 SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
378 <H2><a name="Preprocessor_typemap_delimiters"></a>7.9 Preprocessor and Typemaps</H2>
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:
389 #define SWIG_macro(CAST) (CAST)$input
390 %typemap(in) Int {$1= SWIG_macro(int);}
412 #define SWIG_macro(CAST) (CAST)$input
413 %typemap(in,noblock=1) Int {$1= SWIG_macro(int);}
433 #define SWIG_macro(CAST) (CAST)$input
434 %typemap(in) Int %{$1=SWIG_macro(int);%}
444 arg1=SWIG_macro(int);
449 <H2><a name="Preprocessor_nn10"></a>7.10 Viewing preprocessor output</H2>
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.
459 <H2><a name="Preprocessor_warning_error"></a>7.11 The #error and #warning directives</H2>
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.
471 #error "This is a fatal error message"
472 #warning "This is a warning message"
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:
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