/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
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <title>SWIG Preprocessor</title>
- </head>
- <body bgcolor="#ffffff">
- <a name="n1"></a><H1>6 Preprocessing</H1>
- <!-- INDEX -->
- <ul>
- <li><a href="#n2">File inclusion</a>
- <li><a href="#n3">File imports</a>
- <li><a href="#n4">Conditional Compilation</a>
- <li><a href="#n5">Macro Expansion</a>
- <li><a href="#n6">SWIG Macros</a>
- <li><a href="#n7">C99 Extensions</a>
- <li><a href="#n8">Preprocessing and %{ ... %} blocks</a>
- <li><a href="#n9">Preprocessing and { ... }</a>
- </ul>
- <!-- INDEX -->
- SWIG includes its own enhanced version of the C preprocessor. The preprocessor
- supports the standard preprocessor directives and macro expansion rules.
- However, a number of modifications and enhancements have been made. This
- chapter describes some of these modifications.
- <a name="n2"></a><H2>6.1 File inclusion</H2>
- To include another file into a SWIG interface, use the <tt>%include</tt> directive
- like this:
- <blockquote>
- <pre>
- %include "pointer.i"
- </pre>
- </blockquote>
- Unlike, <tt>#include</tt>, <tt>%include</tt> includes each file once (and will not
- reload the file on subsequent <tt>%include</tt> declarations). Therefore, it
- is not necessary to use include-guards in SWIG interfaces.
- <p>
- By default, the <tt>#include</tt> is ignored unless you run SWIG with the
- <tt>-includeall</tt> option. The reason for ignoring traditional includes
- is that you often don't want SWIG to try and wrap everything included
- in standard header system headers and auxilliary files.
- <a name="n3"></a><H2>6.2 File imports</H2>
- SWIG provides another file inclusion directive with the <tt>%import</tt> directive.
- For example:
- <blockquote>
- <pre>
- %import "foo.i"
- </pre>
- </blockquote>
- The purpose of <tt>%import</tt> is to collect certain information from another
- SWIG interface file or a header file without actually generating any wrapper code.
- Such information generally includes type declarations (e.g., <tt>typedef</tt>) as well as
- C++ classes that might be used as base-classes for class declarations in the interface.
- The use of <tt>%import</tt> is also important when SWIG is used to generate
- extensions as a collection of related modules. This is advanced topic and is described
- in a later chapter.
- <P>
- The <tt>-importall</tt> directive tells SWIG to follow all <tt>#include</tt> statements
- as imports. This might be useful if you want to extract type definitions from system
- header files without generating any wrappers.
- <a name="n4"></a><H2>6.3 Conditional Compilation</H2>
- SWIG fully supports the use of <tt>#if</tt>, <tt>#ifdef</tt>,
- <tt>#ifndef</tt>, <tt>#else</tt>, <tt>#endif</tt> to conditionally
- include parts of an interface. The following symbols are predefined
- by SWIG when it is parsing the interface:
- <p>
- <blockquote><pre>
- SWIG Always defined when SWIG is processing a file
- SWIGTCL Defined when using Tcl
- SWIGTCL8 Defined when using Tcl8.0
- SWIGPERL Defined when using Perl
- SWIGPERL5 Defined when using Perl5
- SWIGPYTHON Defined when using Python
- SWIGGUILE Defined when using Guile
- SWIGRUBY Defined when using Ruby
- SWIGJAVA Defined when using Java
- SWIGMZSCHEME Defined when using Mzscheme
- SWIGWIN Defined when running SWIG under Windows
- SWIGMAC Defined when running SWIG on the Macintosh
- </pre></blockquote>
- In addition, SWIG defines the following set of standard C/C++ macros:
- <blockquote>
- <pre>
- __LINE__ Current line number
- __FILE__ Current file name
- __STDC__ Defined to indicate ANSI C
- __cplusplus Defined when -c++ option used
- </pre>
- </blockquote>
- Interface files can look at these symbols as necessary to change the
- way in which an interface is generated or to mix SWIG directives with
- C code. These symbols are also defined within the C code generated by
- SWIG (except for the symbol `<tt>SWIG</tt>' which is only defined
- within the SWIG compiler).<p>
- <a name="n5"></a><H2>6.4 Macro Expansion</H2>
- Traditional preprocessor macros can be used in SWIG interfaces. Be aware that the <tt>#define</tt> statement
- is also used to try and detect constants. Therefore, if you have something like this in your file,
- <blockquote>
- <pre>
- #ifndef _FOO_H 1
- #define _FOO_H 1
- ...
- #endif
- </pre>
- </blockquote>
- you may get some extra constants such as <tt>_FOO_H</tt> showing up in the scripting interface.
- <p>
- More complex macros can be defined in the standard way. For example:
- <blockquote>
- <pre>
- #define EXTERN extern
- #ifdef __STDC__
- #define _ANSI(args) (args)
- #else
- #define _ANSI(args) ()
- #endif
- </pre>
- </blockquote>
- The following operators can appear in macro definitions:
- <ul>
- <li><tt>#x</tt><br>
- Converts macro argument <tt>x</tt> to a string surrounded by double quotes ("x").
- <p>
- <li><tt>x ## y</tt><br>
- Concatenates x and y together to form <tt>xy</tt>.
- <p>
- <li><tt>`x`</tt><br>
- If <tt>x</tt> is a string surrounded by double quotes, do nothing. Otherwise, turn into a string
- like <tt>#x</tt>. This is a non-standard SWIG extension.
- </ul>
- <a name="n6"></a><H2>6.5 SWIG Macros</H2>
- SWIG provides an enhanced macro capability with the <tt>%define</tt> and <tt>%enddef</tt> directives.
- For example:
- <blockquote>
- <pre>
- %define ARRAYHELPER(type,name)
- %inline %{
- type *new_ ## name (int nitems) {
- return (type *) malloc(sizeof(type)*nitems);
- }
- void delete_ ## name(type *t) {
- free(t);
- }
- type name ## _get(type *t, int index) {
- return t[index];
- }
- void name ## _set(type *t, int index, type val) {
- t[index] = val;
- }
- %}
- %enddef
- ARRAYHELPER(int, IntArray)
- ARRAYHELPER(double, DoubleArray)
- </pre>
- </blockquote>
- The primary purpose of <tt>%define</tt> is to define large macros of code. Unlike normal C preprocessor
- macros, it is not necessary to terminate each line with a continuation character (\)--the macro definition
- extends to the first occurrence of <tt>%enddef</tt>. Furthermore, when such macros are expanded,
- they are reparsed through the C preprocessor. Thus, SWIG macros can contain all other preprocessor
- directives except for nested <tt>%define</tt> statements.
- <p>
- The SWIG macro capability is a very quick and easy way to generate large amounts of code. In fact,
- many of SWIG's advanced features and libraries are built using this mechanism (such as C++ template
- support).
- <a name="n7"></a><H2>6.6 C99 Extensions</H2>
- SWIG-1.3.12 and newer releases support variadic preprocessor macros. For example:
- <blockquote>
- <pre>
- #define DEBUGF(fmt,...) fprintf(stderr,fmt,__VA_ARGS__)
- </pre>
- </blockquote>
- When used, any extra arguments to <tt>...</tt> are placed into the
- special variable <tt>__VA_ARGS__</tt>. This also works with special SWIG
- macros defined using <tt>%define</tt>.
- <p>
- SWIG allows a variable number of arguments to be empty. However, this often results
- in an extra comma (,) and syntax error in the resulting expansion. For example:
- <blockquote>
- <pre>
- DEBUGF("hello"); --> fprintf(stderr,"hello",);
- </pre>
- </blockquote>
- To get rid of the extra comma, use <tt>##</tt> like this:
- <blockquote>
- <pre>
- #define DEBUGF(fmt,...) fprintf(stderr,fmt, ##__VA_ARGS__)
- </pre>
- </blockquote>
- <b>Comment:</b> It's not entirely clear how variadic macros might be useful to
- interface building. However, they are used internally to implement a number of
- SWIG directives and are provided to make SWIG more compatible with C99 code.
- <a name="n8"></a><H2>6.7 Preprocessing and %{ ... %} blocks</H2>
- The SWIG preprocessor does not process any text enclosed in a code block %{ ... %}. Therefore,
- if you write code like this,
- <blockquote>
- <pre>
- %{
- #ifdef NEED_BLAH
- int blah() {
- ...
- }
- #endif
- %}
- </pre>
- </blockquote>
- the contents of the <tt>%{ ... %}</tt> block are copied without
- modification to the output (including all preprocessor directives).
- <a name="n9"></a><H2>6.8 Preprocessing and { ... }</H2>
- SWIG always runs the preprocessor on text appearing inside <tt>{ ... }</tt>. However,
- sometimes it is desirable to make a preprocessor directive pass through to the output
- file. For example:
- <blockquote>
- <pre>
- %extend Foo {
- void bar() {
- #ifdef DEBUG
- printf("I'm in bar\n");
- #endif
- }
- }
- </pre>
- </blockquote>
- By default, SWIG will interpret the <tt>#ifdef DEBUG</tt> statement. However, if you really wanted that code
- to actually go into the wrapper file, prefix the preprocessor directives with <tt>%</tt> like this:
- <blockquote>
- <pre>
- %extend Foo {
- void bar() {
- %#ifdef DEBUG
- printf("I'm in bar\n");
- %#endif
- }
- }
- </pre>
- </blockquote>
- SWIG will strip the extra <tt>%</tt> and leave the preprocessor directive in the code.
- <p><hr>
- <address>SWIG 1.3 - Last Modified : May 25, 2002</address>
- </body>
- </html>