/tags/ttn-post-libtool-1-4-3-upgrade/SWIG/Doc/Manual/Preprocessor.html
HTML | 302 lines | 236 code | 64 blank | 2 comment | 0 complexity | 7c91844a81139094d92265c2e8428d17 MD5 | raw file
Possible License(s): LGPL-2.1, Cube, GPL-3.0, 0BSD, GPL-2.0
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<title>SWIG Preprocessor</title>
5</head>
6
7<body bgcolor="#ffffff">
8<a name="n1"></a><H1>6 Preprocessing</H1>
9<!-- INDEX -->
10<ul>
11<li><a href="#n2">File inclusion</a>
12<li><a href="#n3">File imports</a>
13<li><a href="#n4">Conditional Compilation</a>
14<li><a href="#n5">Macro Expansion</a>
15<li><a href="#n6">SWIG Macros</a>
16<li><a href="#n7">C99 Extensions</a>
17<li><a href="#n8">Preprocessing and %{ ... %} blocks</a>
18<li><a href="#n9">Preprocessing and { ... }</a>
19</ul>
20<!-- INDEX -->
21
22
23
24SWIG includes its own enhanced version of the C preprocessor. The preprocessor
25supports the standard preprocessor directives and macro expansion rules.
26However, a number of modifications and enhancements have been made. This
27chapter describes some of these modifications.
28
29<a name="n2"></a><H2>6.1 File inclusion</H2>
30
31
32To include another file into a SWIG interface, use the <tt>%include</tt> directive
33like this:
34
35<blockquote>
36<pre>
37%include "pointer.i"
38</pre>
39</blockquote>
40
41Unlike, <tt>#include</tt>, <tt>%include</tt> includes each file once (and will not
42reload the file on subsequent <tt>%include</tt> declarations). Therefore, it
43is not necessary to use include-guards in SWIG interfaces.
44
45<p>
46By default, the <tt>#include</tt> is ignored unless you run SWIG with the
47<tt>-includeall</tt> option. The reason for ignoring traditional includes
48is that you often don't want SWIG to try and wrap everything included
49in standard header system headers and auxilliary files.
50
51<a name="n3"></a><H2>6.2 File imports</H2>
52
53
54SWIG provides another file inclusion directive with the <tt>%import</tt> directive.
55For example:
56
57<blockquote>
58<pre>
59%import "foo.i"
60</pre>
61</blockquote>
62
63The purpose of <tt>%import</tt> is to collect certain information from another
64SWIG interface file or a header file without actually generating any wrapper code.
65Such information generally includes type declarations (e.g., <tt>typedef</tt>) as well as
66C++ classes that might be used as base-classes for class declarations in the interface.
67The use of <tt>%import</tt> is also important when SWIG is used to generate
68extensions as a collection of related modules. This is advanced topic and is described
69in a later chapter.
70
71<P>
72The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> statements
73as imports. This might be useful if you want to extract type definitions from system
74header files without generating any wrappers.
75
76<a name="n4"></a><H2>6.3 Conditional Compilation</H2>
77
78
79SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>,
80<tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally
81include parts of an interface. The following symbols are predefined
82by SWIG when it is parsing the interface:
83
84<p>
85<blockquote><pre>
86SWIG Always defined when SWIG is processing a file
87SWIGTCL Defined when using Tcl
88SWIGTCL8 Defined when using Tcl8.0
89SWIGPERL Defined when using Perl
90SWIGPERL5 Defined when using Perl5
91SWIGPYTHON Defined when using Python
92SWIGGUILE Defined when using Guile
93SWIGRUBY Defined when using Ruby
94SWIGJAVA Defined when using Java
95SWIGMZSCHEME Defined when using Mzscheme
96SWIGWIN Defined when running SWIG under Windows
97SWIGMAC Defined when running SWIG on the Macintosh
98</pre></blockquote>
99
100In addition, SWIG defines the following set of standard C/C++ macros:
101
102<blockquote>
103<pre>
104__LINE__ Current line number
105__FILE__ Current file name
106__STDC__ Defined to indicate ANSI C
107__cplusplus Defined when -c++ option used
108</pre>
109</blockquote>
110
111Interface files can look at these symbols as necessary to change the
112way in which an interface is generated or to mix SWIG directives with
113C code. These symbols are also defined within the C code generated by
114SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined
115within the SWIG compiler).<p>
116
117<a name="n5"></a><H2>6.4 Macro Expansion</H2>
118
119
120Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the <tt>#define</tt> statement
121is also used to try and detect constants. Therefore, if you have something like this in your file,
122
123<blockquote>
124<pre>
125#ifndef _FOO_H 1
126#define _FOO_H 1
127...
128#endif
129</pre>
130</blockquote>
131you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
132
133<p>
134More complex macros can be defined in the standard way. For example:
135
136<blockquote>
137<pre>
138#define EXTERN extern
139#ifdef __STDC__
140#define _ANSI(args) (args)
141#else
142#define _ANSI(args) ()
143#endif
144</pre>
145</blockquote>
146
147The following operators can appear in macro definitions:
148
149<ul>
150<li><tt>#x</tt><br>
151Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x").
152
153<p>
154<li><tt>x ## y</tt><br>
155Concatenates x and y together to form <tt>xy</tt>.
156
157<p>
158<li><tt>`x`</tt><br>
159If <tt>x</tt> is a string surrounded by double quotes, do nothing. Otherwise, turn into a string
160like <tt>#x</tt>. This is a non-standard SWIG extension.
161</ul>
162
163<a name="n6"></a><H2>6.5 SWIG Macros</H2>
164
165
166SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives.
167For example:
168
169<blockquote>
170<pre>
171%define ARRAYHELPER(type,name)
172%inline %{
173type *new_ ## name (int nitems) {
174 return (type *) malloc(sizeof(type)*nitems);
175}
176void delete_ ## name(type *t) {
177 free(t);
178}
179type name ## _get(type *t, int index) {
180 return t[index];
181}
182void name ## _set(type *t, int index, type val) {
183 t[index] = val;
184}
185%}
186%enddef
187
188ARRAYHELPER(int, IntArray)
189ARRAYHELPER(double, DoubleArray)
190</pre>
191</blockquote>
192
193The primary purpose of <tt>%define</tt> is to define large macros of code. Unlike normal C preprocessor
194macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition
195extends to the first occurrence of <tt>%enddef</tt>. Furthermore, when such macros are expanded,
196they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor
197directives except for nested <tt>%define</tt> statements.
198
199<p>
200The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact,
201many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template
202support).
203
204<a name="n7"></a><H2>6.6 C99 Extensions</H2>
205
206
207SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example:
208
209<blockquote>
210<pre>
211#define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__)
212</pre>
213</blockquote>
214
215When used, any extra arguments to <tt>...</tt> are placed into the
216special variable <tt>__VA_ARGS__</tt>. This also works with special SWIG
217macros defined using <tt>%define</tt>.
218
219<p>
220SWIG allows a variable number of arguments to be empty. However, this often results
221in an extra comma (,) and syntax error in the resulting expansion. For example:
222
223<blockquote>
224<pre>
225DEBUGF("hello"); --> fprintf(stderr,"hello",);
226</pre>
227</blockquote>
228
229To get rid of the extra comma, use <tt>##</tt> like this:
230
231<blockquote>
232<pre>
233#define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__)
234</pre>
235</blockquote>
236
237<b>Comment:</b> It's not entirely clear how variadic macros might be useful to
238interface building. However, they are used internally to implement a number of
239SWIG directives and are provided to make SWIG more compatible with C99 code.
240
241<a name="n8"></a><H2>6.7 Preprocessing and %{ ... %} blocks</H2>
242
243
244The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore,
245if you write code like this,
246
247<blockquote>
248<pre>
249%{
250#ifdef NEED_BLAH
251int blah() {
252 ...
253}
254#endif
255%}
256</pre>
257</blockquote>
258
259the contents of the <tt>%{ ... %}</tt> block are copied without
260modification to the output (including all preprocessor directives).
261
262<a name="n9"></a><H2>6.8 Preprocessing and { ... }</H2>
263
264
265SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>. However,
266sometimes it is desirable to make a preprocessor directive pass through to the output
267file. For example:
268
269<blockquote>
270<pre>
271%extend Foo {
272 void bar() {
273 #ifdef DEBUG
274 printf("I'm in bar\n");
275 #endif
276 }
277}
278</pre>
279</blockquote>
280
281By default, SWIG will interpret the <tt>#ifdef DEBUG</tt> statement. However, if you really wanted that code
282to actually go into the wrapper file, prefix the preprocessor directives with <tt>%</tt> like this:
283
284<blockquote>
285<pre>
286%extend Foo {
287 void bar() {
288 %#ifdef DEBUG
289 printf("I'm in bar\n");
290 %#endif
291 }
292}
293</pre>
294</blockquote>
295
296SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
297
298<p><hr>
299
300<address>SWIG 1.3 - Last Modified : May 25, 2002</address>
301</body>
302</html>