Preface

During the last time many new features have been developed as additions to the Spirit [4] parser construction framework and we felt more and more, that it would be very helpful, to have a 'real world' example, which could be used as a sandbox for testing the usability of certain features. Additionally a recent discussion on the Boost mailing list showed the widespread interest of developers to have a modern, open source C++ preprocessor library to play with.  So we had the idea to implement a C++ preprocessor to fit this needs - Wave was born.

The Wave C++ preprocessor library uses the Spirit[4] parser construction library to implement a C++ lexer with ISO/ANSI Standards conformant preprocessing capabilities. It exposes an iterator interface, which returns the current preprocessed token from the input stream. This preprocessed token is generated on the fly while iterating over the preprocessor iterator sequence (in the terminology of the STL these iterators are forward iterators).

The C++ preprocessor is a macro processor that under normal circumstances is used automatically by your C++ compiler to transform your program before actual compilation. It is called a macro processor because it allows to define macros, which are brief abbreviations for longer constructs. The C++ preprocessor provides four separate facilities that you can use as you see fit:

 Inclusion of header files
 Macro expansion
 Conditional compilation
 Line control

These features are greatly underestimated today, even more, the preprocessor has been frowned on for so long that its usage just hasn't been effectively pushed until the Boost preprocessor library [7] came into being a few years ago. Only today we begin to understand, that preprocessor generative metaprogramming combined with template metaprogramming in C++ is by far one of the most powerful compile-time reflection/metaprogramming facilities that any language has ever supported.

The C++ Standard [2] was adopted back in 1998, but there is still no (known to me) commercial C++ compiler, which has a bugfree implementation of the rather simple preprocessor requirements mandated therein. This may be a result of the mentioned underestimation or even banning of the preprocessor from good programming style during the last few years or may stem from the somewhat awkward standardese dialect of English used to describe it. Two open source projects are exceptions of this: gcc and Clang (a subproject of LLVM), both providing preprocessors with very good standards conformance.

So the main goals for the Wave project are:

 full conformance with the C++ standard (ISO/IEC 14882:1998) [1] and with the C99 standard (INCITS/ISO/IEC 9899:1999) [2]
 usage of Spirit[4] for the parsing parts of the game (certainly :-)
 maximal usage of STL and/or Boost libraries (for compactness and maintainability)
 straightforward extendability for the implementation of additional features
 building a flexible library for different C++ lexing and preprocessing needs

At the first steps it is not planned to make a very high performance or very small C++ preprocessor. If you are looking for these objectives you probably have to look at other places. Although our C++ preprocessor iterator works as expected and is usable as a reference implementation, for instance for testing of other preprocessor oriented libraries as the Boost Preprocessor library [7] et.al. Nevertheless recent work has lead to surprising performance enhancements (if compared with earlier versions). Wave is still somewhat slower as for instance EDG based preprocessors (Intel, Comeau) on simple input files, however, as complexity increases, time dilates exponentially on EDG. Preprocessing time dilates linearly under Wave, which causes it to easily outperform EDG based preprocessors when complexity increases.

As tests showed, the Wave library is very conformant to the C++ Standard, such that it compiles several strict conformant macro definitions, which are not even compilable with EDG based preprocessors (i.e. Comeau or Intel).