Click here to Skip to main content
15,860,859 members
Articles / Programming Languages / C++

Wave: a Standard conformant C++ preprocessor library

Rate me:
Please Sign up or sign in to vote.
4.96/5 (58 votes)
10 Jan 200413 min read 392.1K   4.4K   81  
Describes a free and fully Standard conformant C++ preprocessor library
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Wave Driver</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="theme/style.css" rel="stylesheet" type="text/css">
</head>

<body>
<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
  <tr> 
    <td width="21"> <h1></h1></td>
    <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The 
      Wave Driver</font></b></font></td>
    <td width="96"><a href="http://spirit.sf.net"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
  </tr>
</table>
<br>
<table border="0">
  <tr> 
    <td width="10"></td>
    <td width="30"><a href="index.html"><img src="theme/u_arr.gif" border="0"></a></td>
    <td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/l_arr.gif" border="0"></a></td>
    <td width="20"><a href="tracing_facility.html"><img src="theme/r_arr.gif" border="0"></a></td>
  </tr>
</table>
<p>There is implemented a driver program for the <tt>Wave</tt> library, which 
  utilizes the capabilities of the library. It is usable as a preprocessor executable 
  on top of any other C++ compiler. It outputs the textual representation of the 
  preprocessed tokens generated from a given input file. This driver program has 
  the following command line syntax:</p>
<pre>Usage: wave [options] [@config-file(s)] file:
 
  Options allowed on the command line only:
    -h [--help]:            print out program usage (this message)
    -v [--version]:         print the version number
    -c [--copyright]:       print out the copyright statement
    --config-file filepath: specify a config file (alternatively: @filepath)
 
  Options allowed additionally in a config file:
    -o [--output] path:          specify a file to use for output instead of stdout
    -I [--include] path:         specify an additional include directory
    -S [--sysinclude] syspath:   specify an additional system include directory
    -F [--forceinclude] file:    force inclusion of the given file
    -D [--define] macro[=[value]]:    specify a macro to define
    -P [--predefine] macro[=[value]]: specify a macro to predefine
    -U [--undefine] macro:       specify a macro to undefine
    -n [--nesting] depth:        specify a new maximal include nesting depth
	
  Extended options (allowed everywhere)
    -t [--traceto] path:    output trace info to a file [path] or to stderr [-]
    --variadics:            enable variadics and placemarkers in C++ mode
    --c99:                  enable C99 mode (implies variadics and placemarkers)
    --c++0x:                enable C++0x support (implies --variadics)
 
</pre>
<P dir="ltr">The possible options are straightforward and self explanatory. The 
  following describes some of these options in more detail. Please note, that 
  the extended options (--c99 and --variadics) are available only, if the driver 
  was compiled with the constant <tt>WAVE_SUPPORT_VARIADICS_PLACEMARKERS</tt> 
  defined. </P>
<P dir="ltr">-o [--output] path</P>
<blockquote> 
  <p dir="ltr">Specify a filename to be used for the generated preprocessed output 
    stream. If this option is not given, then the standard output is used (stdout).</p>
</blockquote>
<P dir="ltr">-I [--include] option</P>
<blockquote> 
  <p dir="ltr">Add the given directory to the head of the list of directories 
    to be searched for header files. This can be used to override a system header 
    file, substituting your own version, since these directories are searched 
    before the system header file directories. If you use more than one '-I' option, 
    the directories are scanned in left-to-right order, the system directories 
    come after. </p>
</blockquote>
<p dir="ltr">-I- [--include-] option</p>
<blockquote> 
  <p dir="ltr">The <tt>Wave</tt> library maintains two separate search pathes 
    for include files. A search path for user include files and a search path 
    for system include files. Any directories specified with '-I' options before 
    an eventually given '-I-' option are searched only for the case of '#include&nbsp;&quot;file&quot;' 
    (user include files), they are not searched for '#include&nbsp;&lt;file&gt;' 
    directives (system include files). If additional directories are specified 
    with '-I' options after a '-I-' option was given, these directories are searched 
    for all '#include' directives. In addition, the '-I-' option inhibits the 
    use of the current directory as the first search directory for '#include &quot;file&quot;' 
    directives. Therefore, the current directory is searched only if it is requested 
    explicitly with a '-I.' option. Specifying both '-I-' and '-I.' allows to 
    control precisely which directories are searched before the current one and 
    which are searched after.</p>
</blockquote>
<p dir="ltr">-S [--sysinclude] option</p>
<blockquote> 
  <p dir="ltr">Add the given directory to the head of the list of directories 
    to be searched for system header files. If you use more than one '-S' option, 
    the directories are scanned in left-to-right order. This option is most useful 
    in the wave.cfg configuration file to specify, where the system include files 
    are to be searched.</p>
</blockquote>
<p dir="ltr">-F [--forceinclude] option</p>
<blockquote> 
  <p dir="ltr">Process the given file as normal input and include all the resulting 
    output before the processing the regular input file starts. If more than one 
    such option is given, the files are pre-included in the sequence of its occurance 
    on the command line.</p>
</blockquote>
<p dir="ltr">-D [--define] macro[=definition]<br>-P [--predefine] macro[=definition]</p>
<blockquote> 
  <p dir="ltr">This option allows to define ('-D') or predefine ('-P') a macro 
    from the command line. The string given in conjunction with the '-D' or '-P' 
    option should conform to the usual syntax MACRO(x)=definition as is described 
    in more detail <a href="class_reference_context.html#add_macro_definition">here</a>.</p>
  <p dir="ltr"> The only difference between the '-D' and the '-P' options is, 
    that the latter predefines a macro such, that it is <b>not</b> undefinable 
    through an <tt>#undef</tt> directive from inside the preprocessed program.</p>
</blockquote>
<p dir="ltr">-U [--undefine] option</p>
<blockquote> 
  <p dir="ltr">This allows to undefine some of the automatically predefined macros 
    of the <tt>Wave</tt> library (see Predefined macros). The only exception are 
    the <code class="keyword">__LINE__</code>, <code class="keyword">__FILE__</code>, 
    <code class="keyword">__DATE__</code>, <code class="keyword">__TIME__</code>, 
    <code class="keyword">__STDC__</code> and <code class="keyword">__cplusplus</code> 
    predefined macros, which are not undefinable. If -U and -D are both specified 
    for one name, the name is not predefined.</p>
</blockquote>
<p dir="ltr">-n [--nesting] depth</p>
<blockquote> 
  <p dir="ltr">Specify a new maximal include nesting depth. If the preprocessing 
    reaches this include file nesting depth, it aborts the preprocessing after 
    emitting an error message. The default include file nesting depth is 1024.</p>
</blockquote>
<p dir="ltr">-t [--traceto] path</p>
<blockquote> 
  <p dir="ltr">Enable the tracing facility build into the <tt>Wave</tt> library. 
    The path specifies the filename to use for the output of the generated trace 
    log. If the filename given equals to <tt>'-'</tt> (without the quotes), the 
    trace log is put into the standard error stream (stderr).</p>
</blockquote>
<p dir="ltr">--variadics</p>
<blockquote> 
  <p dir="ltr">Enables support for variadics (macros with variable parameter lists), 
    placemarkers (empty macro arguments) and <tt>operator&nbsp;_Pragma</tt> in 
    normal C++ mode. This option predefines a special predefined macro <tt>__WAVE_HAS_VARIADICS__</tt>.</p>
</blockquote>
<p dir="ltr">--c99</p>
<blockquote> 
  <p dir="ltr">Enable the C99 mode. This mode enables certain C99 specific features 
    as variadics (macros with variable parameter lists), placemarkers (empty macro 
    arguments) and <tt>operator&nbsp;_Pragma</tt> support and disables some C++ 
    specific token types as for <tt>'::'</tt>, <tt>'-&gt;*'</tt> and <tt>'-&gt;.'</tt>. 
    Several predefined macros are different for this mode, for more information 
    about predefined macros you may look <a href="predefined_macros.html">here</a>. 
    <br>
    Note that the --c99 and the --c++0x options are mutually exclusive. If both 
    options are given a diagnostic is provided and the C99 mode is assumed.</p>
</blockquote>
<p dir="ltr">--c++0x</p>
<blockquote> 
  <p dir="ltr">Enable the (experimental) C++0x mode. This mode enables certain 
    C++ features, which are to be proposed for the new C++ Standard as macro scopes, 
    variadics, placemarkers and well defined pasting of unrelated tokens.<br>
    Note that the --c99 and the --c++0x options are mutually exclusive. If both 
    options are given a diagnostic is provided and the C99 mode is assumed.</p>
  <p dir="ltr">This option is available only, if the library was compiled with 
    the <tt>WAVE_ENABLE_CPP0X_EXTENSIONS</tt> compile time constant defined (for 
    more information about this constant please refere <a href="compiletime_config.html">here</a>).</p>
  </blockquote>
<p dir="ltr">@ [--config-file] option</p>
<blockquote> 
  <p dir="ltr">Some of the possible command line options may be specified inside 
    of special configuration files. This is very useful, as a shorthand for different 
    global configurations. A config file may contain additional options (-I, -S, 
    -F, -U, -D and -P options), one option per line. Empty lines and lines beginning 
    with a '#' character are ignored (are treated as a comment lines). Note that 
    the '#' character is treated as the beginning of a comment only, if it is 
    the first non-whitespace character on a line.</p>
  <p dir="ltr"> There is a shorthand for specifying a configuration file on the 
    command line: simply use the '@' character immediatly before the corresponding 
    file name.</p>
  <p dir="ltr"> The options found in a configuration file are interpreted, as 
    if they were place instead of the configuration file option on the command 
    line.</p>
</blockquote>
<p dir="ltr">The <tt>Wave</tt> driver program looks at startup for a configuration 
  file named 'wave.cfg' in the same directory, where it was startet from (where 
  is located the driver executable). If this file exists, it is treated as a normal 
  configuration file and the specified herein options are interpreted as if they 
  were given as the first options on the command line. This feature is very useful 
  for defining a global environment for the <tt>Wave</tt> preprocessor driver.</p>
<table border="0">
  <tr> 
    <td width="10"></td>
    <td width="30"><a href="./index.html"><img src="theme/u_arr.gif" border="0"></a></td>
    <td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/l_arr.gif" border="0"></a></td>
    <td width="20"><a href="tracing_facility.html"><img src="theme/r_arr.gif" border="0"></a></td>
  </tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003 Hartmut Kaiser<br>
  <br>
  <font size="2">Permission to copy, use, modify, sell and distribute this document 
  is granted provided this copyright notice appears in all copies. This document 
  is provided &quot;as is&quot; without express or implied warranty, and with 
  no claim as to its suitability for any purpose. </font> </p>
<span class="updated">Last updated: 
  <!-- #BeginDate format:fcAm1m -->Thursday, May 8, 2003  22:19<!-- #EndDate -->
  </span></body>
</html>

By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
United States United States
Actively involved in Boost and the development of the Spirit parser construction framework.

Comments and Discussions