boost/wave
2
0
Fork 0
mirror of https://github.com/boostorg/wave.git synced 2026-02-22 15:52:22 +00:00
Code Issues Projects Releases Wiki Activity

Added Wave review candidate to repository.

Browse Source 
[SVN r1909]
This commit is contained in:
Hartmut Kaiser
2004-01-26 06:23:58 +00:00
parent b683dba9be
commit bb119d710a
140 changed files with 74210 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
doc/acknowledgements.html Normal file
View File

@@ -0,0 +1,85 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Acknowledgements</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="theme/style.css" type="text/css">
</head>
<body text="#000000" background="theme/bkd.gif">
<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">Acknowledgements</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="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>Special thanks to:</p>
<blockquote>
<p> <b>Paul Mensonides</b> for his invaluable help while developing the macro
expansion engine and his insightful tips. He developed the recursive macro
expansion algorithm implemented herein and also contributed most of the small
testcases used for testing the correctness of the macro expansion.</p>
<p><b>Dan Nuffer</b>, who wrote the initial Re2C based C++ lexer and the Slex
(Spirit Lex) scanner generator sample.</p>
<p><b>Martin Wille</b> for helping with the port to linux and for contributing
the automated test scripts.</p>
<p><b>Vladimir Prus</b> for helping with the command line and config file options
analysis fro the <tt>Wave</tt> driver executable.</p>
<p><b>Juan Carlos Arevalo-Baeza</b>, who wrote the Spirit cpp_lexer sample,
from which are taken some ideas.</p>
<p> <strong>Andrei Alexandrescu</strong> for allowing to use his flex_string class,
a policy based std::basic_string&lt;&gt; compatible string implementation.</p>
<p><strong>Reece Dunn</strong>, <strong>Vesa Karvonen</strong>, <strong>Faisal Vali</strong>, <strong>Porter Schermerhorn</strong> and <strong>Daniel Fontijne</strong> for
reporting several problems and bugs.</p>
<p><strong>Tarmo Pikaro</strong> for reporting several bug while compiling specific
headers from the Microsoft Windows SDK.</p>
</blockquote>
<p>and last but not least </p>
<blockquote>
<p><b>Joel de Guzman</b> for nudging me into this adventure and for his work
on the <tt>Spirit</tt> parser framework, without which the <tt>Wave</tt> library
wouldn't have been possible.</p>
</blockquote>
<p>The <tt>Wave</tt> library uses the following <tt>Boost</tt> <a href="references.html#boost">[8]</a>
libraries:</p>
<blockquote>
<p><b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"></b>&nbsp;Boost
Spirit (LL parser framework that represents parsers directly as EBNF grammars
in inlined C++)<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"></b> Boost
Iterator Adaptor Library (Adapt a base type into a standard conforming iterator)<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"></b> Boost
Filesystem Library (Portable paths, iteration over directories, and other
useful filesystem operations)<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"></b>&nbsp;Program
options and arguments library</p>
</blockquote>
<p>and other small parts of different <tt>Boost</tt> libraries. </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="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Thursday, January 22, 2004 18:00<!-- #EndDate -->
</span>
</body>
</html>

447
doc/class_reference_context.html Normal file
View File

@@ -0,0 +1,447 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Context Object</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="theme/style.css" type="text/css">
</head>
<body text="#000000" background="theme/bkd.gif">
<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
Context Object</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="quickstart.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_inputpolicy.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_context.html#introduction">Introduction</a><br>
<a href="class_reference_context.html#header_synopsis">Header 'wave/context.hpp' synopsis</a><br>
<a href="class_reference_context.html#public_typedefs">Public Typedefs</a><br>
<a href="class_reference_context.html#template_parameters">Template parameters</a><br>
<a href="class_reference_context.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>The <tt>wave::context&lt;&gt;</tt> object is the main user visible object of
the <tt>Wave</tt> library. It exists to generate the pair of iterators, which
while iterated return the preprocessed tokens. Additionally it is to be used
to control other aspects of the preprocessing, such as </p>
<blockquote>
<p><STRONG><IMG id="IMG1" height="13" src="theme/bullet.gif" width="13"></STRONG>&nbsp;include
search pathes, which define, where to search for files to be included with
<tt>#include&nbsp;&lt;...&gt;</tt> and <tt>#include&nbsp;"..."</tt> directives<br>
<STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>which
macros to predefine and which of the predefined macros to undefine<br>
<STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>several
other options as for instance to control, whether to enable several extensions
to the C++ Standard (as for instance variadics and placemarkers) or not.</p>
</blockquote>
<h2><b><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/cpp_context.hpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">wave/context.hpp</a>
synopsis</b></h2>
<pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {
<span class="keyword">namespace</span> <span class="identifier">wave</span> {
<span class="keyword">template</span> &lt;
<span class="keyword">typename</span> IteratorT, <span class="keyword">typename</span> LexIteratorT,
<span class="keyword">typename</span> InputPolicyT, <span class="keyword">typename</span> TracePolicyT
&gt;
<span class="keyword">class</span> context : <span class="keyword">public</span> InputPolicyT
{
<span class="keyword">public</span>:
<span class="keyword">typedef</span> pp_iterator&lt;context&gt; iterator_t;
<span class="keyword">typedef</span> TokenT token_t;
<span class="keyword">typedef</span> <span class="keyword">typename</span> token_t::position_t position_t;
<span class="comment">// constructor</span>
<a href="class_reference_context.html#constructor">context</a>(IteratorT <span class="keyword">const</span> &amp;first_,
IteratorT <span class="keyword">const</span> &amp;last_,
<span class="keyword">char const</span> *fname = <span class="string">"&lt;Unknown&gt;"</span>,
TracePolicyT &amp;trace = TracePolicyT())
<span class="comment">// iterator interface</span>
iterator_t <a href="class_reference_context.html#iterator_interface_begin">begin</a>() <span class="keyword">const</span>;
iterator_t <a href="class_reference_context.html#iterator_interface_end">end</a>() <span class="keyword">const</span>;
<span class="comment">// maintain include paths</span>
<span class="keyword">bool</span> <a href="class_reference_context.html#add_include_path">add_include_path</a>(<span class="keyword">char const</span> *path_);
<span class="keyword">bool</span> <a href="class_reference_context.html#add_sysinclude_path">add_sysinclude_path</a>(<span class="keyword">char const</span> *path_);
<span class="keyword">void</span> <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter</a>();
size_t <a href="class_reference_context.html#get_iteration_depth">get_iteration_depth</a>() <span class="keyword">const</span>;
<span class="comment">// maintain defined macros</span>
<span class="keyword">bool</span> <a href="class_reference_context.html#add_macro_definition">add_macro_definition</a>(<span class="keyword">std::string</span> macrostring,
<span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>);
<span class="keyword">bool</span> <a href="class_reference_context.html#is_defined_macro">is_defined_macro</a>(<span class="keyword">std::string const</span> &amp;name) <span class="keyword">const</span>;
<span class="keyword">bool</span> <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition</a>(<span class="keyword">std::string const</span> &amp;name,
<span class="keyword">bool</span> even_predefined = <span class="keyword">false</span>);
<span class="keyword">void</span> <a href="class_reference_context.html#reset_macro_definitions">reset_macro_definitions</a>();
<span class="comment">// other options</span>
<span class="keyword">void</span> <a href="class_reference_context.html#language_support">set_language</a>(wave::language_support enable);
wave::language_support <a href="class_reference_context.html#language_support">get_language</a>() <span class="keyword">const</span>;<br>
<span class="keyword">void</span> <a href="class_reference_context.html#set_max_include_nesting_depth">set_max_include_nesting_depth</a>(size_t new_depth);<br> size_t <a href="class_reference_context.html#set_max_include_nesting_depth">get_max_include_nesting_depth</a>() <span class="keyword">const</span>;<br>
<span class="comment">// get the Wave version information </span>
<span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version</a>();
<span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version_string</a>();
};
} <span class="comment">// namespace wave</span>
} <span class="comment">// namespace boost</span></pre>
<h2><b><a name="template_parameters"></a>Template parameters</b></h2>
<p>The <tt>boost::wave::context</tt> object has three template parameters to specify
the concrete behaviour of its operation. The following table describes these
with more detail.</p>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Template parameters required for the
<tt>boost::wave::context</tt> class </b></td>
</tr>
<tr>
<td width="32%" class="table_cells"><code>IteratorT</code></td>
<td width="68%" class="table_cells"><p>The type of the underlying iterator,
through which the input stream is accessed. <br>
This should be at least an <tt>forward_iterator</tt> type iterator.</p></td>
</tr>
<tr>
<td class="table_cells"><code>LexIteratorT</code></td>
<td class="table_cells"><p>The type of the lexer type to be used by the <tt>Wave</tt>
library to identify tokens in the input stream.</p></td>
</tr>
<tr>
<td class="table_cells"><code>InputPolicyT</code></td>
<td class="table_cells"><p>The type of the input policy class, which allows
to customize the behaviour of the Wave library and the type of the iterators
to use, when it comes to including and opening an included file.</p></td>
</tr>
<tr>
<td class="table_cells"><code>TracePolicyT</code></td>
<td class="table_cells"><p>The type of the trace policy class, which allows
to customize the trace output generated while expanding macros. </p></td>
</tr>
</table>
<p>For further information about the lexer type to use, please refer to the <a href="class_reference_lexer.html">The
Lexer Interface </a>.</p>
<p>If the template parameter <tt>InputPolicyT</tt> is omitted, the template <tt>wave::iteration_context_policies::load_file_to_string</tt>
is used. For further information about the input policy, please refer to the
topic <a href="class_reference_inputpolicy.html">The Input Policy</a>.</p>
<p>If the template parameter TracePolicyT is omitted, the <tt>wave::macro_trace_policies::no_tracing</tt>
policy type is used, i.e. by default there is no tracing performed. For further
information about the tracing policy, please refer to the topic <a href="class_reference_tracepolicy.html">The
Tracing Policy</a>. </p>
<h2><a name="public_typedefs"></a>Public Typedefs</h2>
<p>The <tt>boost::wave::context</tt> template defines the following public typedefs, which may be useful while using this class:</p>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Public typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
</tr>
<tr>
<td class="table_cells"><code>iterator_t</code></td>
<td class="table_cells"><p>The <tt>IteratorT</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
</tr>
<tr>
<td class="table_cells"><code>lex_t</code></td>
<td class="table_cells"><p>The <tt>LexIteratorT</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
</tr>
<tr>
<td width="32%" class="table_cells"><code>token_t</code></td>
<td width="68%" class="table_cells"><p>The token type, which is returned by the <tt>context</tt> generated iterators. This type is taken from the <tt>LexIteratorT</tt> template parameter provided, whicle the <tt>context</tt> class was instantiated.</p></td>
</tr>
<tr>
<td class="table_cells"><code>input_policy_t</code></td>
<td class="table_cells"><p>The <tt>InputPolicyT</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
</tr>
<tr>
<td class="table_cells"><code>trace_policy_t</code></td>
<td class="table_cells">The <tt>TracePolicyT</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </td>
</tr>
<tr>
<td class="table_cells"><code>position_t</code></td>
<td class="table_cells"><p>The type of the position information contained in every returned token, which describes the point, at which the given token was recognised. </p></td>
</tr>
</table>
<h2><b><a name="member_functions"></a>Member functions</b></h2>
<p><b><a name="constructor" id="constructor"></a>Constructor</b></p>
<pre> context(IteratorT <span class="keyword">const</span> &amp;first,
IteratorT <span class="keyword">const</span> &amp;last,
<span class="keyword">char const</span> *filename,
TracePolicyT &amp;trace);</pre>
<blockquote>
<p>Constructs a context object on top of the input stream given by the pair
of auxilliary iterators <tt>[first,&nbsp;last)</tt>. The iterators should
be at least <tt>forward_iterator</tt> type iterators. The filename parameter
is to be supplied for informational purposes only. This string is used for
indicating the token positions inside the input stream, it is not validated
against the file system. If the filename parameter is not given it defaults
to <span class="copyright">&quot;&lt;Unknown&gt;&quot;</span>. If the trace
parameter isn't supplied it defaults to a default constructed <tt>TracePolicyT</tt>
object. </p>
<p>Additionally the macro symbol table is filled with the predefined macros
and the current reference directory is set to the path of the given filename.
If this filename does not reference valid file system item, the current reference
directory is set to the current system directory. (The current reference directory
is the file system path, which is used as the target directory during the
processing of <tt>#include&nbsp;&quot;...&quot;</tt> directives),</p>
</blockquote>
<h3>Iterator interface</h3>
<p>The pair of iterators returned by the <tt>context::begin</tt> and <tt>context::end</tt>
functions is the main interface for accessing the preprocessed tokens from the
preprocessor engine. While iterating over the given iterator range <tt>[begin,&nbsp;end)</tt>
there are returned the preprocessed C++ tokens, which are generated on the fly
from the underlying input stream. The returned iterators are conceptually of
<tt>forward_iterator</tt> type.</p>
<p><b><a name="iterator_interface_begin"></a></b><b>begin</b></p>
<pre> iterator_t begin();</pre>
<blockquote>
<p>Initializes and returns the starting iterator for the preprocessed token
stream.</p>
</blockquote>
<p><b><a name="iterator_interface_end" id="iterator_interface_end"></a></b><b>end</b></p>
<pre> iterator_t end() <span class="keyword">const</span>;</pre>
<blockquote>
<p>Initializes and returns the end of stream iterator to compare with for detecting
the end of the preprocessed token stream.</p>
</blockquote>
<h3>Maintain include paths</h3>
<p>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 the <a href="#add_include_path">add_include_path()</a>
function before the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>
is called are searched only for the case of <tt>#include&nbsp;&quot;...&quot;</tt>
directives, they are not searched for <tt>#include&nbsp;&lt;file&gt;</tt> directives.
I.e. these directories are added to the user include search path. </p>
<p>If additional directories are specified with the <a href="#add_include_path">add_include_path()</a>
function after a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>,
these directories are searched for all <tt>#include</tt> directives. I.e. these
directories are added to the system include search path.</p>
<p>In addition, a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>
inhibits the use of the current reference directory as the first search directory
for <tt>#include&nbsp;&quot;...&quot;</tt> directives. Therefore, the current
reference directory is searched only, if it is requested explicitly with a call
to the function <a href="#add_include_path">add_include_path(&quot;.&quot;)</a>.
</p>
<p>Callig both functions, the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>
and <a href="#add_include_path">add_include_path(&quot;.&quot;)</a> allows you
to control precisely, which directories are searched before the current one
and which are searched after.</p>
<p>These functions are modelled after the command line behaviour implemented by
the popular gcc compiler.<br>
</p>
<p><a name="add_include_path"></a><b>add_include_path</b></p>
<pre> <span class="keyword">bool</span> add_include_path(<span class="keyword">char const</span> *path);
</pre>
<blockquote>
<p>Adds the given file system path to the user include search paths. After a
call to the <a href="#set_sys_include_delimiter">set_sysinclude_delimiter()</a>
this function adds the given file system path to the system include search
paths. Note though, that the given path is validated against the file system.
</p>
<p>If the given path string does not form a name of a valid file system directory
item, the function returns <tt>false</tt>. If the given path was successfully
added to the include search paths in question, the function returns <tt>true</tt>.</p>
</blockquote>
<p><a name="add_sysinclude_path"></a><b>add_sysinclude_path</b></p>
<pre> <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path);</pre>
<blockquote>
<p>Adds the given file system path to the system include search paths. This
function operates on the system include search path regardless of the mode
of operation of the <a href="#add_include_path">add_include_path()</a>. Note
though, that the given path is validated against the file system.</p>
<p>If the given path string does not form a name of a valid file system directory
item, the function returns <tt>false</tt>. If the given path was successfully
added to the system include search paths, the function returns <tt>true</tt>.</p>
</blockquote>
<p><a name="set_sysinclude_delimiter" id="set_sysinclude_delimiter"></a><b>set_sysinclude_delimiter</b></p>
<pre> <span class="keyword">void</span> set_sysinclude_delimiter();</pre>
<blockquote>
<p>Switches the mode, how the <a href="#add_include_path">add_include_path()</a>
function operates. By default the given file system path is added to the user
include search paths. After calling this function a subsequent call to the
<a href="#add_include_path">add_include_path()</a> adds the given file system
path to the system include search paths. Additionally it inhibits the the
use of the current reference directory as the first search directory for <tt>#include&nbsp;&quot;...&quot;</tt>
directives.</p>
</blockquote>
<p><a name="get_iteration_depth"></a><b>get_iteration_depth</b></p>
<pre> size_t get_iteration_depth() <span class="keyword">const</span>;</pre>
<blockquote>
<p>Returns the actual include iteration depth, i.e. the current number of include
levels to be poped from the include iteration context, before the main (topmost)
iteration context is reached.</p>
</blockquote>
<h3>Maintain defined macros</h3>
<p><a name="add_macro_definition"></a><b>add_macro_definition</b></p>
<pre><span class="keyword"> bool</span> add_macro_definition(
<span class="keyword">std::string</span> macrostring,
bool is_predefined);
</pre>
<blockquote>
<p>Adds a new macro definition to the macro symbol table. The parameter <tt>macrostring</tt>
should contain the macro to define in the command line format, i.e. something
like <tt>MACRO(x)=definition</tt>. The following table describes this format
in more detail. The parameter <tt>is_predefined</tt> should be true while
defining predefined macros, i.e. macros, which are not undefinable with an
<tt>#undef</tt> directive from inside the preprocessed input stream. If this
parameter is not given, it defaults to <tt>false</tt>.</p>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of possible formats for defining
macros </b></td>
</tr>
<tr>
<td width="32%" class="table_cells"><code>MACRO</code></td>
<td width="68%" class="table_cells"><code>define <tt>MACRO</tt> as 1</code></td>
</tr>
<tr>
<td class="table_cells"><code>MACRO=</code></td>
<td class="table_cells"><code>define <tt>MACRO</tt> as nothing (empty)</code></td>
</tr>
<tr>
<td class="table_cells"><code>MACRO=definition</code></td>
<td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td>
</tr>
<tr>
<td width="32%" class="table_cells"><code>MACRO(x)</code></td>
<td width="68%" class="table_cells"><code>define <tt>MACRO(x)</tt> as 1</code></td>
</tr>
<tr>
<td class="table_cells"><code>MACRO(x)=</code></td>
<td class="table_cells"><code>define <tt>MACRO(x)</tt> as nothing (empty)</code></td>
</tr>
<tr>
<td class="table_cells"><code>MACRO(x)=definition</code></td>
<td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td>
</tr>
</table>
<p>The function returns <tt>false</tt>, if the macro to define already was defined
and the new definition is equivalent to the existing one, it returns true,
if the new macro was successfully added to the macro symbol table.</p>
<p>If the given macro definition resembles a redefinition and the new macro
is not identical to the already defined macro (in the sense defined by the
C++ Standard), the function throws a corresponding <tt>preprocess_exception</tt>.</p>
</blockquote>
<p><a name="is_defined_macro"></a><b>is_defined_macro</b></p>
<pre><span class="keyword"> bool</span> is_defined_macro(<span class="keyword">std::string const</span> &amp;name) <span class="keyword">const</span>; </pre>
<blockquote>
<p>Returns, if a macro with the given <tt>name</tt> is defined, i.e. if it is
contained in the macro symbol table.</p>
</blockquote>
<p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p>
<pre><span class="keyword"> bool</span> remove_macro_definition(
<span class="keyword">std::string const</span> &amp;name,
<span class="keyword">bool</span> even_predefined); </pre>
<blockquote>
<p>Removes the definition of the macro with the given <tt>name</tt> from the
macro symbol table. This operation is equivalent to an <tt>#undef</tt> directive
with this <tt>name</tt> executed from within the input stream. If the parameter
<tt>even_predefined</tt> is <tt>true</tt>, then the macro is removed from
the macro symbol table even, if it is defined as a predefined macro. </p>
<p>Note though, that the following macros are <b>not</b> undefinable in any
case: <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt>,
<tt>__cplusplus</tt>, <tt>__STDC__</tt>. If the parameter <tt>even_predefined</tt>
is not given, it defaults to <tt>false</tt>.</p>
<p>The function returns <tt>false</tt>, if the macro to undefine was not defined
and returns <tt>true</tt> otherwise.</p>
<p>If the macro to remove may not be undefined (it is a predefined macro and
the parameter <tt>even_predefined</tt> is set to <tt>false</tt> or it is one
of the mentioned not undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p>
</blockquote>
<p><a name="reset_macro_definitions"></a><b>reset_macro_definitions</b></p>
<pre><span class="keyword"> void</span> reset_macro_definitions(); </pre>
<blockquote>
<p>Resets the macro symbol table to it's initial state, i.e. undefines all user
defined macros and inserts the internal predefined macros as described <a href="predefined_macros.html">here</a>.</p>
</blockquote>
<h3><a name="get_version"></a>Get Version information</h3>
<p><b>get_version</b></p>
<pre><span class="keyword"> </span><span class="keyword">static std::string</span> get_version(); </pre>
<blockquote>
<p>Returns a string containing the current Wave version formatted as <span class="string">0xvvrsbbbb</span>
(this is a string representation of the equivalent hexadecimal number), where
<span class="literal">'vv'</span> is the version number, <span class="literal">'r'</span>
the release number, <span class="literal">'s'</span> the subrelease number
and <span class="literal">'bbbb'</span> the build number. A possible return
value looks like <span class="literal">0x00910454</span>. The returned value
is the same as is inserted in the preprocessed token stream, when the predefined
macro <tt>__WAVE_VERSION__</tt> is expanded.</p>
</blockquote>
<p><b>get_version_str</b></p>
<pre><span class="keyword"> </span><span class="keyword">static std::string</span> get_version_str(); </pre>
<blockquote>
<p>Returns a string containing the current Wave version formatted as <span class="string">&quot;v.rr.ss.bbbb&quot;</span>,
where <span class="literal">'v'</span> is the version number, <span class="literal">'rr'</span>
the release number, <span class="literal">'ss'</span> the subrelease number
and <span class="literal">'bbbb'</span> the build number. A possible return
value looks like <span class="literal">&quot;0.9.1.454&quot;</span>. The returned
value is the same as is inserted in the preprocessed token stream, when the
predefined macro <tt>__WAVE_VERSION_STR__</tt> is expanded.</p>
</blockquote>
<h3>Control extended options</h3>
<p><a name="support_variadics_and_placemarkers"></a>set_language<br>
get_language</p>
<pre><span class="keyword"> void</span> set_language(<span class="keyword">wave::language_support</span> language);
<span class="keyword">wave::language_support</span> get_language() <span class="keyword">const</span>;</pre>
<blockquote>
<p>This functions allow to specify the language mode, in which the <tt>Wave</tt>
library should work. The possible language modes are defined by the enumerated
type <tt>wave::language_support</tt>:</p>
<pre> <span class="keyword">enum</span> language_support {
<span class="comment">// support flags for C++98</span>
support_normal = 0x01,
support_cpp = support_normal,
<span class="comment">// support flags for C99</span>
support_variadics = 0x02,
support_c99 = support_variadics,
<span class="comment">// support flags for experimental C++0x features</span>
support_extensions = 0x04,
support_cpp0x = support_normal |
support_variadics |
support_extensions,
};</pre>
<p>When used with <tt>support_variadics</tt> the support for variadics, placemarkers
and the <tt>operator _Pragma()</tt> is enabled in normal C++ mode. The <tt>support_c99</tt>
and <tt>support_cpp0x</tt> switch to the respective language support.</p>
</blockquote>
<p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br>
g et_max_include_nesting_depth</p>
<pre><span class="keyword"> void</span> set_max_include_nesting_depth(size_t new_depth);
size_t get_max_include_nesting_depth() <span class="keyword">const</span>;</pre>
<blockquote>
<p>This functions allow to set or to get the maximal possible include file nesting
depth supported by the <tt>Wave</tt> library. The initial value for this is
determined by the preprocessing constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt>
(see <a href="compiletime_config.html">here</a>).</p>
</blockquote>
<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="quickstart.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_inputpolicy.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Sunday, January 18, 2004 10:53<!-- #EndDate -->
</span>
<p>&nbsp;</p>
</body>
</html>

120
doc/class_reference_fileposition.html Normal file
View File

@@ -0,0 +1,120 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The File Position</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
File Position</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="token_ids.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="predefined_macros.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_fileposition.html#introduction">Introduction</a><br>
<a href="class_reference_fileposition.html#header_synopsis">Header 'wave/util/file_position.hpp'
synopsis</a><br>
<a href="class_reference_fileposition.html#template_parameters">Template parameters</a><br>
<a href="class_reference_fileposition.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>The file position template is used to represent a concrete token position inside
the underlying input stream. This token position contains the corresponding
filename, the line number and the column number, where the token was recognized.</p>
<h2><b><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/util/file_position.h?rev=HEAD&content-type=text/vnd.viewcvs-markup">wave/util/file_position.hpp</a>
synopsis</b></h2>
<pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {
<span class="keyword">namespace</span> <span class="identifier">wave</span> {
<span class="keyword">namespace</span> <span class="identifier">util</span> {
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> StringT = <span class="keyword">std::string</span>&gt;
<span class="keyword">class</span> file_position {
<span class="keyword">public</span>:
<a href="class_reference_fileposition.html#constructors">file_position</a>();
<span class="keyword">explicit</span> <a href="class_reference_fileposition.html#constructors">file_position</a>(StringT const &amp;file,
int line_ = 1, int column_ = 1);
// accessors
StringT <span class="keyword">const</span> &amp;<a href="class_reference_fileposition.html#get_accessors">get_file</a>() <span class="keyword">const</span>;
<span class="keyword">int</span> <a href="class_reference_fileposition.html#get_accessors">get_line</a>() <span class="keyword">const</span>;
<span class="keyword">int</span> <a href="class_reference_fileposition.html#get_accessors">get_column</a>() <span class="keyword">const</span>;
<span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_file</a>(StringT <span class="keyword">const</span> &amp;file);
<span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_line</a>(<span class="keyword">int</span> line);
<span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_column</a>(<span class="keyword">int</span> column);
};
} <span class="comment">// namespace util</span>
} <span class="comment">// namespace wave</span>
} <span class="comment">// namespace boost</span></pre>
<h2><a name="template_parameters"></a>Template parameters</h2>
<p>The <tt>file_position</tt> template may be instantiatet with one template parameter,
which gives the string type to use for storing the file name member of the file
position. If this parameter isn't given, it defaults to a <tt>std::string</tt>.
Please note, that the type given as the template parameter must be compatible
with a <tt>std::string</tt>.</p>
<h2><a name="member_functions"></a>Member functions</h2>
<h3><a name="constructors"></a>Constructors</h3>
<pre> <a href="class_reference_fileposition.html#constructors">file_position</a>();
<span class="keyword">explicit</span> <a href="class_reference_fileposition.html#constructors">file_position</a>(StringT const &amp;file,
int line_ = 1, int column_ = 1);
</pre>
<blockquote>
<p>The constructors initialize a new instance of a <tt>file_position</tt> in
correspondence to the supplied parameters. The parameters default to an empty
filename and the line number and column number set to one.</p>
</blockquote>
<p><a name="get_accesssors"></a><b>get_file</b>, <b>get_line</b>, <b>get_column</b></p>
<pre> StringT <span class="keyword">const</span> &amp;<a href="class_reference_fileposition.html#get_accessors">get_file</a>() <span class="keyword">const</span>;
<span class="keyword">int</span> <a href="class_reference_fileposition.html#get_accessors">get_line</a>() <span class="keyword">const</span>;
<span class="keyword">int</span> <a href="class_reference_fileposition.html#get_accessors">get_column</a>() <span class="keyword">const</span>;
</pre>
<blockquote>
<p>The <tt>get_...</tt> functions are used to access the current values of the
file position members: the filename (<tt>get_file</tt>), the line number (<tt>get_line</tt>)
and the column number (<tt>get_column</tt>).</p>
</blockquote>
<p><a name="set_accessors"></a><b>set_file</b>, <b>set_line</b>, <b>set_column</b></p>
<pre> <span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_file</a>(StringT <span class="keyword">const</span> &amp;file);
<span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_line</a>(<span class="keyword">int</span> line);
<span class="keyword">void</span> <a href="class_reference_fileposition.html#set_accessors">set_column</a>(<span class="keyword">int</span> column);
</pre>
<blockquote>
<p>The <tt>set_...</tt> functions are used to set new values to the file position
members: the filename (<tt>set_file</tt>), the line number (<tt>set_line</tt>)
and the column number (<tt>set_column</tt>).</p>
</blockquote>
<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="token_ids.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="predefined_macros.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:25<!-- #EndDate --><!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:26<!-- #EndDate -->

134
doc/class_reference_inputpolicy.html Normal file
View File

@@ -0,0 +1,134 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Input Policy</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
Input Policy</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="class_reference_context.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_tracepolicy.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_inputpolicy.html#introduction">Introduction</a><br>
<a href="class_reference_inputpolicy.html#header_synopsis">Header 'wave/cpp_iteration_context.hpp'
synopsis</a><br>
<a href="class_reference_inputpolicy.html#template_parameters">Template parameters</a><br>
<a href="class_reference_inputpolicy.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>The input policy type may be specified as a template parameter to the <tt>wave::context</tt>
object and is used for customizing the way, how an included file is to be represented
by a pair of iterators pointing to the beginning and the end of the resulting
input sequence. If this template parameter is not given while instantiating
the context object, it defaults to the <tt>iteration_context_policies::load_file_to_string</tt>
type. </p>
<h2><b><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/cpp_iteration_context.hpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">wave/cpp_iteration_context.hpp</a>
synopsis</b></h2>
<p>The following code listing does not show the required interface only, but for
brevity reasons the whole implementation of an input policy, which loads the
given file into a string variable and exposes the begin() and end() iterators
of this string to the <tt>Wave</tt> library.</p>
<pre><span class="keyword">namespace</span> boost {
<span class="keyword">namespace</span> wave {
<span class="keyword">namespace</span> iteration_context_policies {
<span class="keyword">struct</span> load_file_to_string {
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> IterContextT&gt;
<span class="keyword">class</span> inner {
<span class="keyword">public</span>:
<span class="comment">// expose the begin and end iterators for the</span>
<span class="comment">// included file</span>
<span class="keyword">template</span> &lt;typename PositionT&gt;
<span class="keyword">static</span>
<span class="keyword">void</span> <a href="class_reference_inputpolicy.html#init_iterators">init_iterators</a>(IterContextT &iter_ctx,
PositionT const &act_pos)
{
<span class="keyword">typedef typename</span> IterContextT::iterator_t iterator_t;
<span class="keyword">std::ifstream</span> instream(iter_ctx.filename.c_str());
if (!instream.is_open()) {
CPP_THROW(preprocess_exception, bad_include_file,
iter_ctx.filename, act_pos);
}
iter_ctx.instring = <span class="keyword">std::string</span>(
<span class="keyword">std::istreambuf_iterator</span><char>(instream.rdbuf()),
<span class="keyword">std::istreambuf_iterator</span><char>());
iter_ctx.first = iterator_t(iter_ctx.instring.begin(),
iter_ctx.instring.end(),
PositionT(iter_ctx.filename));
iter_ctx.last = iterator_t();
}
<span class="keyword">private</span>:
<span class="keyword">std::string</span> instring;
};
};
} <span class="comment">// namespace iteration_context_policies</span>
} <span class="comment">// namespace wave </span>
} <span class="comment">// namespace boost </span> </pre>
<p>As you can see, an <tt>input_policy</tt> for the <tt>wave::context</tt> object
should implement one function only, the init_iterators function. The policy
shown is implemented with the help of an embedded class to avoid the need for
template template parameters, which aren't implemented by all systems today.
This embedded class should have the name <tt>inner</tt>.</p>
<h3><a name="template_parameters"></a>Template Parameters</h3>
<p>The <tt>inner</tt> class is instantiated with one template parameter, the iteration
context type, from which the policy is a part of. The iterator type <tt>iterator_t</tt>
which is used to access the underlying input stream has to be derived through
a typedef as shown. The iterator pair to initialize (which is accessible as
<tt>iter_ctx.first</tt> and <tt>iter_ctx.last</tt>) has to initialized from
an abritrary iterator type, representing the actual input stream.</p>
<h3><a name="member_functions"></a>Member Functions</h3>
<p><a name="init_iterators"></a><b>init_iterators</b></p>
<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> PositionT&gt;
<span class="keyword">static void</span> init_iterators(
IterContextT iter_ctx,
PositionT const &act_pos);</pre>
<blockquote>
<p>The <tt>init_iterators</tt> function is called, when an <tt>#include</tt>
directive was found in the input token stream. The main rationale for this
function is to initialize the pair of iterators <tt>iter_ctx.first</tt> and
<tt>iter_ctx.last</tt>, which are to be used to access the input stream corresponding
to the include file to be inserted from inside the preprocessing engine.<br>
</p>
</blockquote>
<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="class_reference_context.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_tracepolicy.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:36<!-- #EndDate -->
</span></body>
</html>

103
doc/class_reference_lexer.html Normal file
View File

@@ -0,0 +1,103 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Lexer Interface</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
Lexer Iterator Interface</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="class_reference_tracepolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_tokentype.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_lexer.html#introduction">Introduction</a><br>
<a href="class_reference_lexer.html#header_synopsis">Wave Lexer
synopsis</a><br>
<a href="class_reference_lexer.html#public_typedefs">Public Typedefs</a><br>
<a href="class_reference_lexer.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>Every lexer, which should be used in conjunction with the <tt>Wave</tt> library, has to return tokens formed from the input stream. These tokens should conform to the synopsis described in the topic <a href="class_reference_tokentype.html">The Token Type</a>. The lexer type should expose an interface, which conforms at least to a <tt>forward_iterator</tt> in the sense defined by the the C++ Standard. </p>
<h2><a name="header_synopsis"></a>Wave lexer
synopsis</h2>
<pre> <span class="keyword">struct</span> lex_iterator
{
<span class="keyword">typedef</span> boost::wave::lex_token&lt;&gt; <a href="class_reference_lexer.html#public_typedefs">token_t</a>;
<span class="comment"> // Every lex_iterator should implement at least a complete
// forward_iterator interface (not shown here)
</span><span class="keyword"> typedef</span> std::forward_iterator_tag iterator_category;
<span class="comment"> // additional requirements
</span> <a href="class_reference_lexer.html#member_functions">lex_iterator</a>();
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> IteratorT&gt;
<a href="class_reference_lexer.html#constructor">lex_iterator</a>(IteratorT <span class="keyword">const</span> &amp;first, IteratorT <span class="keyword">const</span> &amp;last
<span class="keyword">typename</span> token_t::position_t <span class="keyword">const</span> &amp;pos,
boost::wave::language_support language)
};
</pre>
<h2><a name="public_typedefs" id="public_typedefs"></a>Public Typedefs</h2>
<p>Besides the typedefs mandated for a <tt>forward_iterator</tt> by the C++ standard every lexer to be used with the <tt>Wave</tt> library should define the following typedefs: </p>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Public typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
</tr>
<tr>
<td width="32%" class="table_cells"><code>token_t</code></td>
<td width="68%" class="table_cells"><p>The <tt>token</tt> type returned by the lexer. This is type is used as the return value of the main iterators provided by the <tt>boost::wave:.context</tt> object too. </p></td>
</tr>
</table>
<h2><a name="member_functions"></a>Member functions</h2>
<p>Besides the functions, which should be provided for <tt>forward_iterators</tt> as mandated by the C++ Standard, every lexer must implement the following functions to be used with the <tt>Wave</tt> library: </p>
<p><a name="destructor"></a><b>constructor</b></p>
<pre> lex_iterator();</pre>
<blockquote>
<p>The default constructor should construct a lexer iterator, which may be used as the end iterator of the provided iterator range.</p>
</blockquote>
<pre>
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> IteratorT&gt;
lex_iterator(IteratorT <span class="keyword">const</span> &amp;first, IteratorT <span class="keyword">const</span> &amp;last,
<span class="keyword">typename</span> token_t::position_t <span class="keyword">const</span> &amp;pos,
boost::wave::language_support language);</pre>
<blockquote>
<p>The second constructor should construct a lexer iterator, which may be used as a iterator traversing over the token sequence, generated by the lexer class.</p>
<p>The pair of iterators <tt>first</tt> and <tt>last</tt> should represent the input stream to be tokenized by the given lexer class. </p>
<p>The parameter <tt>pos</tt> contains the initial position information to be used for token generation.</p>
<p>The parameter <tt>language</tt> controls the reuqired mode with which the lexer should be initialised. </p>
</blockquote>
<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="class_reference_tracepolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_tokentype.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Sunday, January 18, 2004 12:16<!-- #EndDate -->
</span></body>
</html>
<!-- #BeginDate format:fcAm1m -->Sunday, January 18, 2004 12:16<!-- #EndDate -->

173
doc/class_reference_tokentype.html Normal file
View File

@@ -0,0 +1,173 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Token Type</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="theme/style.css" type="text/css">
</head>
<body text="#000000" background="theme/bkd.gif">
<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
Token Type</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="class_reference_lexer.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="token_ids.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_tokentype.html#introduction">Introduction</a><br>
<a href="class_reference_tokentype.html#header_synopsis">Header 'wave/context.hpp'
synopsis</a><br>
<a href="class_reference_tokentype.html#template_parameters">Template parameters</a><br>
<a href="class_reference_tokentype.html#member_functions">Member functions</a></p>
</blockquote>
<h2><a name="Introduction"></a>Introduction</h2>
<p>The token type in <tt>Wave</tt> is the main carrier of information. It is returned
by dereferencing the main iterator. The tokens are originally generated by the
lexer (&quot;An entity that lexically transforms the subject of parsing to a
sequence of objects (called tokens) more suitable for subsequent parsing.&quot;).
The Wave library contains two different, interchangable C++ lexers, which may
be used as a starting point during developing your own application. The lexer
generated tokens are transformed by the preprocessing engine (macro expansion,
include file processing etc.) and after this returned to the user of the <tt>Wave</tt>
library.</p>
<p>You can use arbitrary token types in conjunction with your own lexer as long
as these implement some required interface. The required token type interface
is described below and is implemented by the <tt>wave::cpplexer::lex_token</tt>
template, the required lexer interface is described <a href="class_reference_lexer.html">here</a>.
</p>
<p>In the following is described the token type predefined inside the <tt>Wave</tt>
library, which is used in conjunction with the two predefined C++ lexers contained
in the <tt>Wave</tt> library too. If you need to use your own token type, it
is required to implement the interafce described below.</p>
<h2><b><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/cpplexer/cpp_lex_token.hpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">wave/cpplexer/cpp_lex_token.hpp</a>
synopsis</b></h2>
<pre><span class="keyword">namespace</span> boost {
<span class="keyword">namespace</span> wave {
<span class="keyword">namespace</span> cpplexer {
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> PositionT&gt;
<span class="keyword">class</span> lex_token
{
<span class="keyword">public</span>:
<span class="keyword">typedef</span> <span class="keyword">std::basic_string</span><char> string_t;
<span class="keyword">typedef</span> PositionT position_t;
<a href="class_reference_tokentype.html#constructor">lex_token</a>();
<a href="class_reference_tokentype.html#constructor">lex_token</a>(token_id id, string_t <span class="keyword">const</span> &value,
PositionT <span class="keyword">const</span> &pos);
// accessors
<a href="class_reference_tokentype.html#operator_tokenid">operator token_id</a>() <span class="keyword">const</span>;
string_t const &amp;<a href="class_reference_tokentype.html#get_value">get_value</a>() <span class="keyword">const</span>;
position_t const &amp;<a href="class_reference_tokentype.html#get_position">get_position</a>() <span class="keyword">const</span>;
void <a href="class_reference_tokentype.html#set_token_id">set_token_id</a> (token_id id);
void <a href="class_reference_tokentype.html#set_value">set_value</a> (string_t <span class="keyword">const</span> &amp;newval);
void <a href="class_reference_tokentype.html#set_position">set_position</a> (position_t <span class="keyword">const</span> &amp;pos);
};
} <span class="comment">// namespace cpplexer</span>
} <span class="comment">// namespace wave</span>
} <span class="comment">// namespace boost</span>
</pre>
<h2><b><a name="template_parameters" id="template_parameters"></a>Template parameters</b></h2>
<p>The predefined token type uses a template parameter <tt>PositionT</tt>, which
allows to specify the type to be used to carry the file position information
contained inside the generated tokens. This type should contain at least the
filename, the line number and the column number of the position, where the token
was recognized. It defaults to a simple file_position template class described
<a href="class_reference_fileposition.html">here</a>. </p>
<h2><b><a name="member_functions"></a>Member functions</b></h2>
<p><b><a name="constructor" id="constructor"></a>Constructors</b></p>
<pre> lex_token();
lex_token(token_id id,
string_t <span class="keyword">const</span> &amp;value,
PositionT <span class="keyword">const</span> &amp;pos);</pre>
<blockquote>
<p>The first (default) constructor is for generating an end of stream token,
which is used for indicating the end of the underlying input stream.</p>
<p>The second constructor initializes the newly created token object with its
token id (for a list of valid token id's please look <a href="token_ids.html">here</a>),
the string representation of its value and the file position, describing the
position inside the input stream , where this token was recognized.</p>
</blockquote>
<h2>Accessor functions</h2>
<p><a name="operator_tokenid"></a><b>operator token_id</b></p>
<pre> <span class="keyword">operator</span> token_id() <span class="keyword">const</span>;</pre>
<blockquote>
<p>Allows the access to the token id of the token. This access function is implemented
as an implicit conversion function to allow the operation of <tt>Spirit</tt>
parsers directly on top of a token stream. The possible token id's are described
<a href="token_ids.html">here</a>. </p>
<p>This function does not throw in any case.</p>
</blockquote>
<p><a name="get_value"></a><b>get_value</b></p>
<pre> string_t <span class="keyword">const</span> &amp;get_value() <span class="keyword">const</span>;</pre>
<blockquote>
<p>Returns the value of the token, as it was recognized in the input stream.
Even for constant tokens (as keywords or operators etc.) the returned value
reflects the character sequence as found in the input stream. </p>
<p>This function does not throw in any case.</p>
</blockquote>
<p><b><a name="get_position"></a>get_position</b></p>
<pre> PositionT <span class="keyword">const</span> &amp;get_position() <span class="keyword">const</span>;</pre>
<blockquote>
<p>Returns the position of the token in the input stream, where it was recognized.
The position contains information about the filename, the line number and
the column number of the token. By default the <tt>Wave</tt> library uses
a file_position template for this purpose, which is described in more detail
<a href="class_reference_fileposition.html">here</a>.</p>
<p>This function does not throw in any case.</p>
</blockquote>
<p><a name="set_token_id"></a><b>set_token_id</b></p>
<pre> void set_token_id(token_id id);</pre>
<blockquote>
<p>Changes the token id of the token to the new value. The possible token id's
are described <a href="token_ids.html">here</a>. Propably this function is
of little value for the library user, but it is required under certain circumstances
for correct operation of the preprocessing engine.</p>
<p>This function does not throw in any case.</p>
</blockquote>
<p><a name="set_value"></a><b>set_value</b></p>
<pre> void set_value(string_t <span class="keyword">const</span> &amp;newval);</pre>
<blockquote>
<p>Changes the value stored inside the token to the new value. Propably this
function is of little value for the library user, but it is required under
certain circumstances for correct operation of the preprocessing engine.</p>
</blockquote>
<p><a name="set_position"></a><b>set_position</b></p>
<pre> void set_position(PositionT <span class="keyword">const</span> &amp;newpos);</pre>
<blockquote>
<p>Changes the position stored inside the token to the new value. This is used
for instance for implementing the functionality required for to implement
the <tt>#line</tt> directive.</p>
</blockquote>
<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="class_reference_lexer.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="token_ids.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:36<!-- #EndDate -->

249
doc/class_reference_tracepolicy.html Normal file
View File

@@ -0,0 +1,249 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Tracing Policy</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
Tracing Policy</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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_tracepolicy.html#introduction">Introduction</a><br>
<a href="class_reference_tracepolicy.html#header_synopsis">Header 'wave/trace_policies.hpp'
synopsis</a><br>
<a href="class_reference_tracepolicy.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>There is implemented an unique tracing facility as a part of the <tt>Wave</tt>
library, which allows to selectively trace all stages of the macro expansion
process, involving the argument expansion and the rescanning of the replacement
results. This tracing facility greatly helps to understand foreign code or to
debug your own macros.</p>
<p>The tracing policy is used to trace the macro expansion of macros whenever
it is requested from inside the input stream to preprocess through the <tt>#pragma&nbsp;wave_option(trace:&nbsp;enable)</tt>
(or <tt>_Pragma(&quot;wave&nbsp;trace(enable)&quot;)</tt>) directive. The macro
tracing may be disabled again with the help of a <tt>#pragma wave_option(trace:
disable)</tt> (or <tt>_Pragma(&quot;wave&nbsp;trace(disable)&quot;)</tt>) directive.
Note though, that the <tt>Wave</tt> driver executable requires additionally
to specify the <tt>-t</tt> (<tt>--trace</tt>) command line option, which defines
the stream, where the trace output goes.</p>
<p>This policy type is used as a template parameter to the <a href="class_reference_context.html"><tt>wave::context&lt;&gt;</tt></a>
object, where the default policy does no tracing at all.</p>
<h2><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/macro_trace_policies.hpp?rev=1.1&content-type=text/vnd.viewcvs-markup">wave/trace_policies.hpp</a>
synopsis</h2>
<pre>
<span class="keyword">namespace</span> boost {
<span class="keyword">namespace</span> wave {
<span class="keyword">namespace</span> trace_policies {
<span class="keyword">enum</span> trace_flags {
trace_nothing = 0, <span class="comment">// disable tracing</span>
trace_macros = 1, <span class="comment">// enable macro tracing</span>
trace_includes = 2 <span class="comment">// enable include file tracing</span>
};
<span class="keyword">struct</span> default_tracing {
<span class="comment">// general control function</span>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#enable_tracing">enable_tracing</a>(trace_flags enable);
trace_flags <a href="class_reference_tracepolicy.html#tracing_enabled">tracing_enabled</a>();
<span class="comment">// macro tracing functions</span>
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanding_function_like_macro">expanding_function_like_macro</a>(TokenT <span class="keyword">const</span> &amp;macrodef,
<span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args,
ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall,
<span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments);
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanding_object_like_macro">expanding_object_like_macro</a>(TokenT <span class="keyword">const</span> &amp;macro,
ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">expanded_macro</a>(ContainerT <span class="keyword">const</span> &amp;result);
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">rescanned_macro</a>(ContainerT <span class="keyword">const</span> &amp;result);
<span class="comment">// include file tracing functions</span>
<span class="keyword">void </span><a href="class_reference_tracepolicy.html#opened_include_file">opened_include_file</a>(std::string <span class="keyword">const</span> &amp;filename,
std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#returning_from_include_file">returning_from_include_file</a>();
<span class="comment">// interpretation of unknown #pragma's</span>
<span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &amp;pending,
TokenT const &amp;option, ContainerT <span class="keyword">const</span> &amp;values,
TokenT <span class="keyword">const</span> &amp;pragma_token, language_support language);
};
} <span class="comment">// namespace macro_trace_policy</span>
} <span <!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:46<!-- #EndDate -->st</span>
</pre>
<h2><a name="member_functions"></a>Member functions</h2>
<h3>General control functions</h3>
<p><a name="enable_tracing"></a><b>enable_tracing</b></p>
<pre> <span class="keyword">void</span> enable_tracing(<span class="keyword">trace_flags</span> enable);</pre>
<blockquote>
<p>The function <tt>enable_tracing</tt> is called, whenever the status of the
tracing was changed from inside the stream to preprocess.</p>
<p>The parameter <tt>enable</tt> is to be used as the new tracing status.</p>
</blockquote>
<p><a name="tracing_enabled"></a><b>tracing_enabled</b></p>
<pre> <span class="keyword">trace_flags</span> tracing_enabled();</pre>
<blockquote>
<p>The function <tt>tracing_enabled</tt> should return the current tracing status.</p>
</blockquote>
<h3>Tracing functions</h3>
<h4>Macro tracing functions</h4>
<p><a name="expanding_function_like_macro"></a><b>expanding_function_like_macro</b></p>
<pre><span class="keyword"> template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> expanding_function_like_macro(TokenT <span class="keyword">const</span> &amp;macrodef,
<span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args,
ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall,
<span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments);</pre>
<blockquote>
<p>The function <tt>expanding_function_like_macro</tt> is called, whenever a
function-like macro is to be expanded, i.e. <i>before</i> the actual expansion
starts.</p>
<p>The <tt>macroname</tt> parameter marks the position, where the macro to expand
is defined. It contains the token, which identifies the macro name used inside
the corresponding macro definition.</p>
<p>The <tt>formal_args</tt> parameter holds the formal arguments used during
the definition of the macro. </p>
<p>The <tt>definition</tt> parameter holds the macro definition for the macro
to trace. This is a standard STL container, which holds the token sequence
identified during the macro definition as the macro replacement list.</p>
<p>The <tt>macrocall</tt> parameter marks the position, where this macro invoked.
It contains the token, which identifies the macro call inside the preprocessed
input stream. </p>
<p>The <tt>arguments</tt> parameter holds the macro arguments used during the
invocation of the macro. This is a vector of standard STL containers, which
contain the token sequences identified at the position of the macro call as
the arguments to be used during the macro expansion. </p>
</blockquote>
<p><a name="expanding_object_like_macro"></a><b>expanding_object_like_macro</b></p>
<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> expanding_object_like_macro(TokenT <span class="keyword">const</span> &amp;macro,
ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
</pre>
<blockquote>
<p>The function <tt>expanding_object_like_macro</tt> is called, whenever a object-like
macro is to be expanded, i.e. <i>before</i> the actual expansion starts.</p>
<p>The <tt>macroname</tt> parameter marks the position, where the macro to expand
is defined. It contains the token, which identifies the macro name used inside
the corresponding macro definition.</p>
<p> The <tt>definition</tt> parameter holds the macro definition for the macro
to trace. This is a standard STL container, which holds the token sequence
identified during the macro definition as the macro replacement list.</p>
<p>The <tt>macrocall</tt> parameter marks the position, where this macro invoked.
It contains the token, which identifies the macro call inside the preprocessed
input stream. </p>
</blockquote>
<p><a name="expanded_macro"></a><b>expanded_macro</b></p>
<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> expanded_macro(ContainerT <span class="keyword">const</span> &amp;result);
</pre>
<blockquote>
<p>The function <tt>expanded_macro</tt> is called, whenever the expansion of
a macro is finished, the replacement list is completely scanned and the identified
macros herein are replaced by its corresponding expansion results, but <i>before</i>
the rescanning process starts.</p>
<p>The parameter <tt>result</tt> contains the the result of the macro expansion
so far. This is a standard STL container containing the generated token sequence.</p>
</blockquote>
<p><a name="rescanned_macro"></a><b>rescanned_macro</b></p>
<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
<span class="keyword">void</span> rescanned_macro(ContainerT <span class="keyword">const</span> &amp;result);
</pre>
<blockquote>
<p>The function <tt>rescanned_macro</tt> is called, whenever the rescanning
of a macro is finished, i.e. the macro expansion is complete.</p>
<p>The parameter <tt>result</tt> contains the the result of the whole macro
expansion. This is a standard STL container containing the generated token
sequence.</p>
</blockquote>
<h4>Include file tracing functions</h4>
<p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p>
<pre> <span class="keyword">void</span> opened_include_file(std::string <span class="keyword">const</span> &amp;filename,
std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
</pre>
<blockquote>
<p>The function <tt>opened_include_file</tt> is called, whenever a file referred
by an #include directive was successfully located and opened.</p>
<p>The parameter <tt>filename</tt> contains the full file system path of the
opened file.</p>
<p>The <tt>include_depth</tt> parameter contains the current include file depth.
</p>
<p>The <tt>is_system_include</tt> parameter denotes, if the given file was found
as a result of a <tt>#include&nbsp;&lt;...&gt;</tt> directive.</p>
</blockquote>
<p><a name="returning_from_include_file" id="returning_from_include_file"></a><strong>returning_from_include_file</strong></p>
<pre> <span class="keyword">void</span> returning_from_include_file();
</pre>
<blockquote>
<p>The function <tt>returning_from_include_file</tt> is called, whenever an
included file is about to be closed after it's processing is complete.</p>
</blockquote>
<p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p>
<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &amp;pending,
TokenT const &amp;option, ContainerT <span class="keyword">const</span> &amp;values,
TokenT <span class="keyword">const</span> &amp;pragma_token, language_support language);
</pre>
<blockquote>
<p>The function <tt>interpret_pragma</tt> is called, whenever an unrecognized
<tt>#pragma&nbsp;wave&nbsp;...</tt> or operator <tt>_Pragma(&quot;wave&nbsp;...&quot;)</tt>
is found in the input stream.</p>
<p>The <tt>pending</tt> parameter may be used to push tokens back into the input
stream, which are to be used as the replacement text for the whole <tt>#pragma&nbsp;wave()</tt>
directive. If this sequence is left empty, no replacement takes place, i.e.
the interpreted directive is removed from the generated token stream.</p>
<p>The <tt>option</tt> parameter contains the name of the interpreted pragma.</p>
<p>The <tt>values</tt> parameter holds the value of the parameter provided to
the pragma operator.</p>
<p>The <tt>pragma_token</tt> parameter contains the actual #pragma token, which
may be used for extraction of the location information for some error output.</p>
<p>The <tt>language</tt> parameter contains the current language mode, in which
the <tt>Wave</tt> library operates.</p>
<p>If the return value is 'false', the whole #pragma directive is interpreted
as unknown and a corresponding error message is issued. A return value of
'true' signs a successful interpretation of the given #pragma.<br>
</p>
</blockquote>
<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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:36<!-- #EndDate -->
</span></body>
</html>

211
doc/compiletime_config.html Normal file
View File

@@ -0,0 +1,211 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Compile Time Configuration</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">Compile
Time Configuration</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="supported_pragmas.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p><b><a name="compiletime_config"></a>Library compile time configuration</b></p>
<P dir="ltr">The C++ preprocessor iterator library may be configured at compile
time by specifying different preprocessor constants to include different additional
features. The possible preprocessor constants are described in the following
table. </P>
<table width="100%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of possible preprocessor constants
for<br>
library configuration</b></td>
</tr>
<tr>
<td width="46%" class="table_cells"><code>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</code></td>
<td width="54%" class="table_cells"> <p>Support the #warning directive</p></td>
</tr>
<tr>
<td width="46%" class="table_cells"><code><code>BOOST_</code>WAVE_SUPPORT_MS_EXTENSIONS</code></td>
<td width="54%" class="table_cells"> <p>Support several MS specific language
extensions (i.e. <tt>__int8</tt> et.al.)</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_PREPROCESS_ERROR_MESSAGE_BODY</code></td>
<td class="table_cells"><p>Enable the preprocessing of the message bodies
of <span class="keyword">#error</span> and <span class="keyword">#warning</span>
directives.</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_RETURN_PRAGMA_DIRECTIVES</code></td>
<td class="table_cells"><p>If defined, then the <span class="keyword">#pragma</span>
directives are returned as a token sequence to the caller, if not defined,
the whole <span class="keyword">#pragma</span> directive is skipped. </p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_PREPROCESS_PRAGMA_BODY</code></td>
<td class="table_cells"><p>Enable the preprocessing of the bodies of <span class="keyword">
#pragma</span> directives.<br>
Note though, that the body of an <tt>operator&nbsp;_Pragma()</tt> is preprocessed
always, as required by the C99 Standard <a href="references.html#iso_c">[2]</a>.
</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_ENABLE_COMMANDLINE_MACROS</code></td>
<td class="table_cells"><p>Enable the functionality required to define macros
with the command line syntax (-DMACRO(x)=definition)</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_STRINGTYPE</code></td>
<td class="table_cells"><p>The tokens generated by the <tt>Wave</tt> library
contain the token data and the file position, where this token was found
in the input stream. <br>
This constant may be used to redefine the data type, which is used to
hold the token data and the corresponding file name. If this isn't defined
it defaults to std::string. (The here defined data type should be compatible
to the std::string type)</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_SUPPORT_VARIADICS_PLACEMARKERS</code></td>
<td class="table_cells"><p>If defined, then the preprocessor library supports
variadics and placemarkers. Note, to support C99 mode, this constant must
be defined too.</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_MAX_INCLUDE_LEVEL_DEPTH</code></td>
<td class="table_cells"><p>If defined, it will determine the initial maximal
possible include file nesting depth supported. It defaults to 1024.</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_ENABLE_CPP0X_EXTENSIONS</code></td>
<td class="table_cells"><p>If defined, then the preprocessor library supports
a couple of experimental C++0x extensions, as macro scopes, variadics
and placemarkers in C++ mode, well defined token pasting of unrelated
tokens. For more details please refer to <a href="preliminary_cpp0x_support.html">The
Preliminary C++0x support</a>.</p></td>
</tr>
<tr>
<td class="table_cells"><code><code>BOOST_</code>WAVE_SUPPORT_PRAGMA_ONCE</code></td>
<td class="table_cells"><p>If defined, then the <code>#pragma once</code> directive is supported by <tt>Wave</tt>. This specifies that the file, in which the pragma resides, will be included
(opened) only once by the compiler in a build. </p></td>
</tr>
<tr>
<td class="table_cells"><code>BOOST_</code><code>WAVE_SUPPORT_INCLUDE_NEXT</code></td>
<td class="table_cells"><p>If defined, then the <code>#include_next</code> directive is supported by <tt>Wave</tt>. This is syntactically equivalent to the <code>#include</code> directives, but may be used to inherit a header file (i.e. to include a file, which is named as the current file containing the <code>#include_next</code>).</p></td>
</tr>
</table>
<P dir="ltr"><b><a name="using_custom_lexer"></a>Using a different token type or lexer type in conjunction with Wave </b></P>
<P dir="ltr">It is possible to use the <tt>Wave</tt> library while using your own token and/or lexer types. This may be achieved by providing your lexer type as the second template parameter while instantiating the <tt>boost::wave::context&lt;&gt;</tt> object. The token type used by the library is derived from the <tt>token_t</tt> typedef to be provided by the lexer type. If you want to provide your own token type only, you may use the <tt>boost::wave::lex_iterator&lt;&gt;</tt> type contained with the library. This type needs to be parametrized with the token type to use. </P>
<P dir="ltr">To show, how this may be done, the <tt>Wave</tt> library contains several samples illustrating this possibility. The <tt>cpp_tokens</tt> sample shows the usage of a custom lexer and a custom token types. The lexer type used is functionally fully compatible to the <tt>re2c</tt> <a href="references.html#re2c">[3]</a> based lexer used by default. It is implemented based on the <tt>SLex</tt> <a href="references.html#slex">[5]</a> lexer example written by Dan Nuffer. The used theiring token type is functionally equivalent to the default token type except for an additional <tt>operator&lt;&lt;</tt> used for dumping the information carried bz the token.</P>
<P dir="ltr"><b><a name="compilation_models"></a>Separation and inclusion compilation
models</b></P>
<P dir="ltr">The <tt>Wave</tt> C++ preprocessor iterator library is build almost
completely as a header only library (except for the re2c based lexer). If you're
trying to include all required files at once you will mention, that the resulting
compilation times are very large (up to an hour - depending on your system configuration).
This straightforward method we'll call the inclusion compilation model. If you
do not pay attention to compilation times, that's the way to go, no special
handling is needed.</P>
<P dir="ltr">If you're interested in decreasing compilation times, the following
method is to be used. This we will call it the separation compilation model.
The trick is to separate the different objects such, that they are compilable
separately. The function, which instantiates the templated object in question
is factored out such, that its definition is visible to only one translation
unit. To simplify this further this creation function is packaged into a small
generator template structure.</P>
<P dir="ltr">There are two levels of separation implemented: the separation of
the compilation of the C++ lexer and the separation of the compilation of the
different Spirit grammars used. To use these separations you will have to define
two preprocessor constants while compiling the whole application and you will
have to explicitely instantiate some helper templates. The following tables
shows these constants in detail.</P>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of possible compilation constants
required <br>
to enable the separation compilation model</b></td>
</tr>
<tr class="table_title">
<td width="25%"><b>Separate</b></td>
<td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Preprocessor
constant</font></code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>C++ lexer</code></td>
<td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_LEXER_INSTANTIATION</code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>Spirit grammars</code></td>
<td width="75%" class="table_cells"> <p><code><code>BOOST_</code>WAVE_SEPARATE_GRAMMAR_INSTANTIATION</code></p></td>
</tr>
</table>
<P dir="ltr">The following table shows the explicit template instantiations required,
if you want to use the separation compilation model. The <tt>TokenT</tt> placeholder
type has to be replaced with your token type to use and the <code><tt>LexIteratorT</tt></code> placeholder type has to be replaced with your lex iterator type you've used while instantiation of the <tt>boost::wave::context&lt;&gt;</tt> object. You will achieve the best
results, if you place these into separate compilation units each. The <tt>IteratorT</tt>
placeholder should be replaced by the iterator type, which was used to instantiate
the <tt>boost::wave::context&lt;&gt;</tt> object.</P>
<table width="90%" border="0" align="center">
<tr>
<td colspan="2" class="table_title"><b>Summary of required explicit template
instantiations <br>
required when using the separation compilation model</b></td>
</tr>
<tr class="table_title">
<td width="25%"><b>Separate</b></td>
<td width="75%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Templates
to explicitly instantiate</font></code></p></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>C++ lexer</code></td>
<td width="75%" class="table_cells"> <code><span class="keyword">template</span>
cpplexer::re2clex::new_lexer_gen&lt;<tt>IteratorT</tt>&gt;;</code></td>
</tr>
<tr>
<td width="25%" class="table_cells"><code>Spirit grammars</code></td>
<td width="75%" class="table_cells"> <p><code><span class="keyword">template</span> wave::grammars::expression_grammar_gen&lt<tt>TokenT</tt>&gt;;<br>
<span class="keyword"> template</span> wave::grammars::intlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
<span class="keyword"> template</span> wave::grammars::chlit_grammar_gen&lt;<tt>TokenT</tt>&gt;;<br>
<span class="keyword"> <code>template</code><code></code><code> wave::grammars::cpp_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;<br>
</code>template</span> wave::grammars::predefined_macros_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;<br>
<span class="keyword"> template</span> wave::grammars::defined_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;</code></p></td>
</tr>
</table>
<p>To see an example of this you can look at the <tt>Wave</tt> driver program
included as an acompanion sample to the C++ preprocessor iterator library. The
corresponding files are named obviously <span class="string">&quot;instantiate_...something.cpp&quot;</span>,
where the <span class="string">'...somthing'</span> is a hint, which grammars
are explicitely instantiated inside. By using the separation model the compilation
times required to build the <tt>Wave</tt> example are dropped by up to 90%.</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="supported_pragmas.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="preliminary_cpp0x_support.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Friday, January 23, 2004 18:13<!-- #EndDate -->
</span></body>
</html>

92
doc/introduction.html Normal file
View File

@@ -0,0 +1,92 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Introduction</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 text="#000000" background="theme/bkd.gif">
<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">Introduction</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="preface.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="quickstart.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<P dir="ltr">The <tt>Wave</tt> C++ preprocessor library is a Standards conformant
implementation of the mandated C++ preprocessor functionality packed behind
a simple to use interface, which integrates well with the well known idioms
of the Standard Template Library (STL).</P>
<P dir="ltr">The <tt>Wave</tt> C++ preprocessor is not a monolitic application,
it's rather a modular library, which exposes mainly a context object and an
iterator interface. The context object helps to configure the actual preprocessing
process (as search path's, predefined macros, etc.). The exposed iterators are
generated by this context object too. Iterating over the sequence defined by
the two iterators will return the preprocessed tokens, which are to be built
on the fly from the given input stream. </P>
<P dir="ltr"> The C++ preprocessor iterator itself is feeded by a C++ lexer iterator,
which implements an unified interface. BTW, the C++ lexers contained with the
<tt>Wave</tt> library may be used standalone too and are not tied to the C++
preprocessor iterator at all. </P>
<P dir="ltr">To make the C++ preprocessing library modular, the C++ lexer is held
completely separate and independend from the preprocessor. To proof this concept,
there are two different C++ lexers and aIDL lexer implemented by now,&nbsp;which are functionally
completely identical. The C++ lexers expose the mentioned unified interface,
so that the C++ preprocessor iterator may be used with both of them. The abstraction
of the C++ lexer from the C++ preprocessor iterator library was done to allow
to plug in different C++ lexers without the need to reimplement the preprocessor.
This will allow for benchmarking and specific finetuning of the process of preprocessing
itself.</P>
<P dir="ltr">The first of this C++ lexers is implemented with the help of the
wellknown <tt>Re2C</tt> <a href="references.html#re2c">[3]</a> tool, which generates
C code from given regular expressions. The lexers generated with <tt>Re2C</tt>
are known to be very fast, because they are not&nbsp;table driven but the whole
token building logic is coded directly (very similar to hand coded lexers).
</P>
<P dir="ltr">The second of this C++ lexers is build around a table driven lexer,
where the DFA tables are generated from regular expressions with the help of
a Spirit based lexer generating framework named <tt>Slex</tt> <a href="references.html#slex">[5]</a>.
The <tt>Slex</tt> is feeded during runtime with the token definitions (regular
expressions) and generates the resulting DFA table. This table is used to combine
the input characters into corresponding lexems (tokens). The generated DFA table
can be saved to disc to avoid the generation process at program startup.</P>
<P dir="ltr">Wave may be used for preprocessing IDL files too, since the token set needed for the IDL language is very similar to the C++ token set. That's the reason, why the <tt>Wave</tt> preprocessor library contains also an IDL lexer. The IDL lexer is based on the <tt>re2c</tt> tool too, but recognizes a different set of tokens. So this lexer does not recognize any keywords (except <tt>true</tt> and <tt>false</tt>, which are needed by the preprocessor itself). This is needed because there exist different IDL languages, where identifiers of one language may be keywords of others. Ok, this implies to postpone keyword identification after the preprocessing, but allows to use <tt>Wave</tt> for all of the IDL derivatives. </P>
<P dir="ltr">It is possible to build other C++ lexers if needed. Currently there
are plans to adapt the <tt>Spirit</tt> C++ lexer example <tt>cpplexer</tt> <a href="references.html#cpplexer">[6]</a>,
which is completely based on static <tt>Spirit<a href="references.html#spirit">[4]</a></tt>
grammars.</P>
<P dir="ltr">In fact both of the embedded lexers and the library itself is able
to act in a C99 compliant mode. In this mode the lexers reject C++ only tokens
(<tt>'::'</tt>, <tt>'-&gt;*'</tt>, <tt>'.*'</tt> and the alternate keywords
as <tt>'and'</tt> etc.). The preprocessor additionally handles placemarkers
(empty macro arguments) and variadics (macros with variable parameter count).
As an extension to the C++ Standard the library can be enabled to handle placemarkers
and variadics in the C++ mode too.</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="preface.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="quickstart.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 18:25<!-- #EndDate -->
</span> </body>
</html>

101
doc/macro_expansion_process.html Normal file
View File

@@ -0,0 +1,101 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Macro Expansion Process</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
Macro Expansion Process</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="supported_pragmas.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="compiletime_config.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>The macro expansion process described here was initially developed by <a href="mailto:pmenso57@attbi.com">Paul
Mensonides</a> and is implemented in <tt>Wave</tt>. It is much more understandable
as the description of the desired macro expansion algorithm provided in the
C++ Standard <a href="references.html#iso_cpp">[1]</a>.</p>
<p>Macro replacement proceeds left-to-right. </p>
<p>If, during scanning (or rescanning) an identifier is found, it is looked up
in the symbol table. If the identifier is not found in the symbol table, it
is not a macro and scanning continues.</p>
<p>If the identifier is found, the value of a flag associated with the identifier
is used to determine if the identifier is available for expansion. If it is
not, the specific token (i.e. the specific instance of the identifier) is marked
as disabled and is not expanded. If the identifier is available for expansion,
the value of a different flag associated with the identifier in the symbol table
is used to determine if the identifier is an object-like or function-like macro.
If it is an object-like macro, it is expanded. If it is a function-like macro,
it is only expanded if the next token is an left parenthesis.<br>
An identifier is available for expansion if it is not marked as disabled and
if the the value of the flag associated with the identifier is not set, which
is used to determine if the identifier is available for expansion.</p>
<p>(If a macro is an object-like macro, skip past the next two paragraphs.)</p>
<p>If a macro to be expanded is a function-like macro, it must have the exact
number of actual arguments as the number of formal parameters required by the
definition of the macro. Each argument is recursively scanned and expanded.
Each parameter name found in the replacement list is replaced by the expanded
actual argument after leading and trailing whitespace and all placeholder tokens
are removed unless the parameter name immediately follows the stringizing operator
(<tt>'#'</tt>) or is adjacent to the token-pasting operator (<tt>'##'</tt>).</p>
<p>If the parameter name immediately follows the stringizing operator (<tt>'#'</tt>),
a stringized version of the unexpanded actual argument is inserted. If the parameter
name is adjacent to the token-pasting operator (<tt>'##'</tt>), the unexpanded
actual argument is inserted after all placeholder tokens are removed.</p>
<p>All concatenation takes place in the replacement list. (If a single concatenation
yields multiple tokens, the behavior is undefined. Moreover, <tt>Wave</tt> in
normal C++98 and C99 modes issues an error, if more then one token is produced
as the result of the concatenation. In C++0x mode <tt>Wave</tt> treats token-pasting
of unrelated tokens as well defined and inserts the reparsed string representation
of the concatenated tokens into the replacement list.).</p>
<p>The flag in the symbol table entry associated with the name of the macro being
expanded is set to indicate the that the macro is not available for expansion.</p>
<p>The replacement list is rescanned for further macro expansion. All leading
and trailing whitespace tokens in the replacement list are removed (the placeholder
tokens are left intact). </p>
<p>After rescanning completes, the flag in the symbol table entry associated with
the name of macro being expanded is cleared to indicate that the macro is again
available for expansion, and the sequence of tokens that constitutes the rescanned
replacement list is returned to the point of invocation of the macro.</p>
<p>If this sequence of tokens is empty, it is replaced by a placeholder token.
If a placeholder is found during scanning (or rescanning) it is ignored. (Also,
if the only thing separating a parameter from the stringizing operator or token-pasting
operator is placeholder, it is also ignored in that context.)</p>
<p>This sequence of tokens is inserted at the original point that the macro was
invoked, and scanning continues starting with the last token of the newly inserted
sequence of tokens. I.e. scanning looks back a single token (possibly a placeholder
token) and continues.<br>
</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="supported_pragmas.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="compiletime_config.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span>
<p>&nbsp; </p>
</body>
</html>

175
doc/predefined_macros.html Normal file
View File

@@ -0,0 +1,175 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Predefined Macros</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">Predefined
Macros </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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="supported_pragmas.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p dir="ltr">The following table lists the macros, which are predefined by the
<tt>Wave</tt> library. Some of these (all except 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__, __INCLUDE_LEVEL__</code>
and <code class="keyword">__cplusplus</code> macros, and in C++0x mode the <code><tt>__STDC_GLOBAL__</tt></code>,
<tt>__STDC_FULL_REGION__</tt> and <tt>__STDC__CURRENT_REGION__</tt> macros are
not undefinable too) may be undefined from the command line of the driver executable
(<a href="wave_driver.html">see</a> the -U option) or through the function <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition()</a>.</p>
<p dir="ltr">In C++0x mode the predefined macros are available at every macro
scope without explicit qualification (except <tt>__STDC_GLOBAL__</tt>, which is available at global macro scope
only).</p>
<table width="90%" border="0" align="center">
<tr>
<td colspan="3" class="table_title"><b>Summary of predefined macros</b></td>
</tr>
<tr class="table_title">
<td width="28%"><b>Name</b></td>
<td width="62%"><p><code><font face="Verdana, Arial, Helvetica, sans-serif">Value</font></code></p></td>
<td width="10%">Undefinable</td>
</tr>
<tr>
<td width="28%" class="table_cells"><code>__STDC__</code></td>
<td width="62%" class="table_cells"><p> 1 (a decimal constant)</p></td>
<td width="10%" class="table_cells"><p>yes</p></td>
</tr>
<tr>
<td width="28%" class="table_cells"><code>__cplusplus</code></td>
<td width="62%" class="table_cells"> <p>199711L (a decimal constant), this
is defined in C++ mode only (C99 mode is off)<br>
In the C++0x mode this decimal constant is guaranteed to be larger than
199711L (the concrete value is to be defined by the C++ committee).</p></td>
<td width="10%" class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__LINE__</code></td>
<td class="table_cells"><p>The line number of the current source line (a decimal
constant)</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__FILE__</code></td>
<td class="table_cells"><p>The presumed name of the source file (a character
string literal)</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__DATE__</code></td>
<td class="table_cells"><p>The date of translation of the source file (a character
string literal of the form<br>
&quot;Mmm dd yyyy&quot;, where the names of the months are the same as
those generated by the asctime function, and the first character of dd
is a space character if the value is less than 10). </p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__TIME__</code></td>
<td class="table_cells"><p>The time of translation of the source file (a character
string literal of the form &quot;hh:mm:ss&quot;<br>
as in the time generated by the asctime function).</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__INCLUDE_LEVEL__</code></td>
<td class="table_cells"><p>A decimal integer constant that represents the
depth of nesting in include <br>
files. The value of this macro is incremented on every <tt>#include</tt>
directive <br>
and decremented at every end of file. </p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__WAVE__</code><br> <code>__SPIRIT_PP__</code></td>
<td class="table_cells"><p>The version of the driver program (a hexadecinal
constant of the form 0xMmrr, where <span class="literal">'M'</span> is
the major version number, <span class="literal">'m'</span> the minor version
number and <span class="literal">'rr'</span> the release number).</p></td>
<td class="table_cells"><p>yes</p></td>
</tr>
<tr>
<td class="table_cells"><code>__WAVE_VERSION__</code><br> <code>__SPIRIT_PP_VERSION__</code></td>
<td class="table_cells"><p>The full version number of the driver program (a
hexadecinal constant of the form 0xMmrrbbbb, where <span class="literal">'M'</span>
is the major version number, <span class="literal">'m'</span> the minor
version number, <span class="literal">'rr'</span> the release number and
<span class="literal">'bbbb'</span> the build number).</p></td>
<td class="table_cells"><p>yes</p></td>
</tr>
<tr>
<td class="table_cells"><code>__WAVE_VERSION_STR__</code><br> <code>__SPIRIT_PP_VERSION_STR__</code></td>
<td class="table_cells"><p>The full version number of the driver program (a
character string literal of the form <span class="string">&quot;M.m.rr.bbbb&quot;</span>,
where <span class="literal">'M'</span> is the major version number, <span class="literal">'m'</span>
the minor version number, <span class="literal">'rr'</span> the release
number and <span class="literal">'bbbb'</span> the build number).</p></td>
<td class="table_cells"><p>yes</p></td>
</tr>
<tr>
<td class="table_cells"><code>__STDC_VERSION__</code></td>
<td class="table_cells"><p>199901L (a decimal constant), this is defined in
C99 mode only</p></td>
<td class="table_cells"><p>yes</p></td>
</tr>
<tr>
<td class="table_cells"><code>__WAVE_HAS_VARIADICS__</code></td>
<td class="table_cells"><p>1 (a decimal constant), this is defined in C++
mode only, if variadics and placemarkers are enabled, further it is defined
in C99 and C++0x modes</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__STDC_GLOBAL__</code></td>
<td class="table_cells"><p>1 (a decimal constant), this is defined in C++0x
mode only and only at global macro scope</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__STDC_CURRENT_REGION__</code></td>
<td class="table_cells"><p>The name of the current active macro region (a
string literal). This constant does not contain the full qualified scope
name, but only it's last part. This macro is defined in C++0x mode only.</p></td>
<td class="table_cells"><p>no</p></td>
</tr>
<tr>
<td class="table_cells"><code>__STDC_FULL_REGION__</code></td>
<td class="table_cells"><p>The name of the current active macro region (a
string literal). This constant does contain the full qualified scope name,
not only it's last part. This macro is defined in C++0x mode only.</p></td>
<td class="table_cells"><p>no</p></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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="supported_pragmas.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:41<!-- #EndDate -->
</span></body>
</html>

109
doc/preface.html Normal file
View File

@@ -0,0 +1,109 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Preface</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 text="#000000" background="theme/bkd.gif">
<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">Preface</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"><img src="theme/l_arr_disabled.gif" width="20" height="19" border="0"></td>
<td width="30"><a href="introduction.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>During the last time many new features were developed as additions to the <tt>Spirit</tt>
<a href="references.html#spirit">[4]</a> 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&nbsp;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.&nbsp; So we had the idea to implement a C++ preprocessor to fit
this needs&nbsp;-&nbsp;<tt>Wave</tt> was born.</p>
<p align="justify">The <tt>Wave</tt> C++ preprocessor library uses the <a href="http://spirit.sourceforge.net/">
</a> <tt>Spirit<a href="references.html#spirit">[4]</a></tt> parser construction
library to implement a C++ lexer with ISO/ANSI standard 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). </p>
<p align="justify"> 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
you 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: </p>
<blockquote>
<p><b><img src="theme/bullet.gif" width="13" height="13" id="IMG1">&nbsp;</b>Inclusion
of header files<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1">&nbsp;</b>Macro
expansion<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1">&nbsp;</b>Conditional
compilation<br>
<b><img src="theme/bullet.gif" width="13" height="13" id="IMG1">&nbsp;</b>Line
control</p>
</blockquote>
<p>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 <a href="references.html#pp_lib">[7]</a>
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.</p>
<p align="justify">The main goals for the <tt>Wave</tt> project are:</p>
<blockquote>
<p><b><img src="theme/bullet.gif" width="13" height="13" id="IMG1">&nbsp;</b>full
conformance with the C++ standard (ISO/IEC 14882:1998) <a href="references.html#iso_cpp">[1]</a>
and with the C99 standard (INCITS/ISO/IEC 9899:1999) <a href="references.html#iso_c">[2]</a><br>
<b><img src="theme/bullet.gif" width="13" height="13">&nbsp;</b>usage of <tt>Spirit<a href="references.html#spirit">[4]</a></tt>
for the parsing parts of the game (certainly :-)<br>
<b><img src="theme/bullet.gif" width="13" height="13">&nbsp;</b>maximal usage
of STL and/or <tt>Boost</tt> libraries (for compactness and maintainability)<br>
<b><img src="theme/bullet.gif" width="13" height="13">&nbsp;</b>straightforward
extendability for the implementation of additional features<br>
<b><img src="theme/bullet.gif" width="13" height="13">&nbsp;</b>building a
flexible library for different C++ lexing and preprocessing needs</p>
</blockquote>
<p>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 should
work as expected and will be usable as a reference implementation, for instance
for testing of other preprocessor oriented libraries as the Boost Preprocessor
library <a href="references.html#pp_lib">[7]</a> et.al.</p>
<p>As tests showed, the <tt>Wave</tt> 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). It
is shown further, that the EDG preprocessor will outperform the <tt>Wave</tt>
preprocessor in simple cases. However, as complexity increases, time dilates
expontentially on EDG. Preprocessing time dilates linearly under <tt>Wave</tt>,
which causes it to easily outperform EDG based preprocessors when complexity
increases.</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"><img src="theme/l_arr_disabled.gif" width="20" height="19" border="0"></td>
<td width="30"><a href="introduction.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>

317
doc/preliminary_cpp0x_support.html Normal file
View File

@@ -0,0 +1,317 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Preliminary C++0x support</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">Preliminary
C++0x support</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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="wave_driver.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>In order to prepare a proposal for the C++ Standards committee, which should
describe certain new and enhanced preprocessor features, the Wave preprocessor
library has implemented experimental support for the following features:</p>
<p><a href="preliminary_cpp0x_support.html#variadic_macros">Variadic macros</a><br>
<a href="preliminary_cpp0x_support.html#placemarker_tokens">Placemarker tokens</a><br>
<a href="preliminary_cpp0x_support.html#token_pasting">Well defined token-pasting</a><br>
<a href="preliminary_cpp0x_support.html#macro_scoping">Macro scoping mechanism</a><br>
<a href="preliminary_cpp0x_support.html#new_alternative_tokens">New alternative tokens</a></p>
<p>The described features are enabled by the <tt>--c++0x</tt> command line option
of the <tt>Wave</tt> driver. Alternatively you can enable these features by
calling the <tt>wave::context&lt;&gt;::set_language()</tt> function with the
<tt>wave::support_cpp0x</tt> value. </p>
<h2><a name="variadic_macros"></a>Variadic macros</h2>
<p>Both variadic macros and placemarker tokens have already been added to C99
<a href="references.html#iso_c">[2]</a>. This represents an unnecessary incompatibility
between C and C++. Adding these facilities to the C++ preprocessor would cause
no code to break that is currently well-defined and would closing the gap between
C and C++ in this field.</p>
<p>Variadic macros were added to the C preprocessor as of C99 <a href="references.html#iso_c">[2]</a>.
They are, effectively, a way to pass a variable number of arguments to a macro.
The specific syntax is as follows:</p>
<pre> <span class="preprocessor">#define</span> A(...) <span class="preprocessor">__VA_ARGS__</span>
<span class="preprocessor">#define</span> B(a, ...) <span class="preprocessor">__VA_ARGS__</span>
A(1, 2, 3) <span class="comment">// expands to: 1, 2, 3</span>
B(1, 2, 3) <span class="comment">// expands to: 2, 3</span>
</pre>
<p>The ellipsis is used to denote that the macro can accept any number of trailing
arguments. It must always occur as the last formal parameter of the macro. The
variadic arguments passed to the macro are identified by the special symbol
<tt>__VA_ARGS__</tt> in the replacement list of a variadic macro. The use of
this symbol is prohibited in any other context.</p>
<h2><a name="placemarker_tokens"></a>Placemarker tokens</h2>
<p>Placemarker tokens (technically, preprocessing tokens) are simply a well-defined
way of passing &quot;nothing&quot; as a macro argument. This facility was also
added to the C preprocessor as of C99 <a href="references.html#iso_c">[2]</a>.</p>
<pre> <span class="preprocessor">#define</span> X(p) f(p)
X(&quot;abc&quot;) <span class="comment">// expands to: f(&quot;abc&quot;)</span>
X() <span class="comment">// expands to: f()</span>
<span class="preprocessor">#define</span> Y(a, b) <span class="keyword">int</span>[a][b]
Y(2, 2) <span class="comment">// expands to: int[2][2]</span>
Y(, 2) <span class="comment">// expands to: int[][2]</span>
</pre>
<p>Placemarker tokens are a natural counterpart to variadic macros. They formalize the optional nature of a variadic argument (or arguments) so that variadic macros appear similar to the variadic functions, but have been generalized to include named parameters as well.
</p>
<h2><a name="token_pasting"></a>Well defined token-pasting</h2>
<p>Currently, as of both C++98 and C99, if token-pasting results in multiple preprocessing
tokens, the behavior is undefined. For example,</p>
<pre> <span class="preprocessor">#define</span> PASTE(a, b) a <span class="preprocessor">##</span> b
PASTE(1, 2) <span class="comment">// okay</span>
PASTE(+, -) <span class="comment">// undefined behavior</span></pre>
<p>Token-pasting of unrelated tokens (i.e. token-pasting resulting in multiple
preprocessing tokens) is currently undefined for no substantial reason. It is
not dependent on architecture nor is it difficult for an implementation to diagnose.
Furthermore, retokenization is what most, if not all, preprocessors already
do and what most programmers already expect the preprocessor to do. Well-defined
behavior is simply standardizing existing practice and removing an arbitrary
and unnecessary undefined behavior from the standard.</p>
<p>To achieve well-defined behavior in this context <tt>Wave</tt> retokenizes
the result of the token-pasting and inserts the newly created token sequence
as the macro replacement text.</p>
<pre> PASTE(+, ==) <span class="comment">// expands to: += =</span></pre>
<h2><a name="macro_scoping"></a>Macro scoping mechanism</h2>
<p>One of the major problems of the preprocessor is that macro definitions do
not respect any of the scoping mechanisms of the core language. As history has
shown, this is a major inconvenience and drastically increases the likelihood
of name clashes within a translation unit. The solution is to add both a named
and unnamed scoping mechanism to the C++ preprocessor. This limits the scope
of macro definitions without limiting its accessibility. Here are the details.
</p>
<p>The scoping mechanism is implemented with the help of three new preprocessor
directives: <span class="preprocessor">#region</span>, <span class="preprocessor">#endregion</span>
and <span class="preprocessor">#import</span>. Additionally it changes minor
details of some of the existing preprocessor directives: <span class="preprocessor">#ifdef</span>,
<span class="preprocessor">#ifndef</span> and the <span class="preprocessor">operator
defined()</span>.</p>
<h3>The #region directive</h3>
<p>The <span class="preprocessor">#region</span> directive starts a new named
or unnamed macro scope.</p>
<h4>Syntax</h4>
<blockquote>
<p><tt>#region &lt;qualified-identifier&gt;</tt></p>
<p> Where <tt>&lt;qualified-identifier&gt;</tt> is an optionally qualified name
defining the name of the region to open.<br>
This name is optional. If the name is omitted a nameless region is opened.
</p>
</blockquote>
<p>If the qualified identifier starts with an <tt>'::'</tt> the name is looked
up relative to the global scope (the <tt>&lt;qualified-identifier&gt;</tt> is
called <em>absolute</em>), if it starts with an identifier, the region is looked
up relative to the current open region (the <tt>&lt;qualified-identifier&gt;</tt>
is called <em>relative</em>). If the specified region is not defined, it is
created. </p>
<p>The <span class="preprocessor">#region</span> directive is opaque for all macro
definitions made outside this region, i.e. no macros defined inside of other
regions or at the global scope are directly accessible from inside the opened
region. To access such macros these must be imported (see the <span class="preprocessor">#import</span>
directive) or must be referred to through it's qualified name. </p>
<p>Regions may be nested. </p>
<p>A region may be re-opened (i.e. a <span class="preprocessor">#region</span>
directive with the same name is found at the same scope), and macros defined
inside the previous occurences of this region will be visible. </p>
<p>Region names and macro names of the same scope are stored into the same symbol
table. This implies, that at one scope there shall not be defined a region and
a macro with the same name.</p>
<p>Macros defined inside a nameless region may not be accessed from outside this
region. Further, from inside a nameless region it is not allowed to open an
enclosed region through an <em>absolute</em> name.</p>
<p>The argument of the <span class="preprocessor">#region</span> directive is
<strong>not</strong> subject to macro expansion before it is evaluated.</p>
<p>The following is a small code sample, which shows possible usages of preprocessor
regions.</p>
<pre> <span class="preprocessor">#define</span> A() 1
<span class="comment">/////////////////////////////////////</span>
<span class="preprocessor">#region</span> region_A
<span class="preprocessor"># define</span> B() 2
<span class="comment">/////////////////////////////////////</span>
<span class="preprocessor"># region</span> region_B
<span class="preprocessor"># define</span> C() 3
A() <span class="comment">// expands to: A()</span>
B() <span class="comment">// expands to: B()</span>
C() <span class="comment">// expands to: 3</span>
<span class="preprocessor"># endregion</span> <span class="comment">// region_B</span>
<span class="comment">/////////////////////////////////////</span>
A() <span class="comment">// expands to: A()</span>
B() <span class="comment">// expands to: 2</span>
C() <span class="comment">// expands to: C()</span>
region_B::C() <span class="comment">// expands to: 3</span>
::region_A::region_B::C() <span class="comment">// expands to: 3</span>
<span class="preprocessor">#endregion</span> <span class="comment">// region_A</span>
<span class="comment">/////////////////////////////////////</span>
A() <span class="comment">// expands to: 1</span>
B() <span class="comment">// expands to: B()</span>
region_A::B() <span class="comment">// expands to: 2</span>
::region_A::B() <span class="comment">// expands to: 2</span>
region_A::region_B::C() <span class="comment">// expands to: 3</span>
::region_A::region_B::C() <span class="comment">// expands to: 3</span>
<span class="preprocessor">#define</span> region_A ... <span class="comment">// error, name clash with region_A</span>
<span class="preprocessor">#region</span> A <span class="comment">// error, name clash with macro A</span>
<span class="preprocessor">#endregion</span>
</pre>
<h3>The #endregion directive</h3>
<p>The <span class="preprocessor">#endregion</span> directive closes the last
macro scope opened with a <span class="preprocessor">#region</span> directive
.</p>
<h4>Syntax</h4>
<blockquote>
<p><tt>#endregion</tt></p>
</blockquote>
<p>The <span class="preprocessor">#endregion</span> directive is opaque for all
macros defined inside the closed region. Macros defined inside this region may
be accessed from outside of this region only if imported (see the <span class="preprocessor">
#import</span> directive) or if referenced through qualified names specifying
the region and the macro name and if the region isn't unnamed.</p>
<p>The <span class="preprocessor">#region</span> and <span class="preprocessor">#endregion</span>
directives shall be balanced over the whole translation unit. Otherwise an error
is raised.</p>
<h3>The #import directive</h3>
<p>The <span class="preprocessor">#import</span> directive allows to import macros
or whole macro scopes into the current macro scope.</p>
<h4>Syntax</h4>
<blockquote>
<p><tt>#import &lt;qualified-identifier&gt; [, &lt;qualified-identifier&gt;
...]</tt></p>
</blockquote>
<blockquote>
<p>Where <tt>&lt;qualified-identifier&gt;</tt> is an optionally qualified name
defining the name of the macro or region to import. The <span class="preprocessor">#import</span>
directive may specify one or more comma separated qualified names.</p>
</blockquote>
<p>If the qualified identifier starts with an <tt>'::'</tt> the name is looked
up relative to the global scope (the <tt>&lt;qualified-identifier&gt;</tt> is
called <em>absolute</em>), if it starts with an identifier, the region is looked
up relative to the current open region (the <tt>&lt;qualified-identifier&gt;</tt>
is called <em>relative</em>). </p>
<p>If <tt>&lt;qualified-identifier&gt;</tt> refers to a macro, then the referenced
macro definition is made available in the current region, just if it were defined
here. Both macro definitions (the original macro definition and the imported
one) refer to the same macro. This is significant for disabling of a certain
macro during the rescanning of a replacement list. If one of the different instances
of the macro definition is marked as disabled for expansion, the others are
marked as disabled for expansion too.</p>
<p>If <tt>&lt;qualified-identifier&gt;</tt> refers to a region, then</p>
<ul>
<li>all macro definitions of the referenced region are made available in the
current region, just if these were defined here.</li>
<li> all sub-regions of the referenced region are made available from the current
region, just if these were defined as direct sub-regions of the current region.</li>
</ul>
<p> Imported macros may be undefined with the <span class="preprocessor">#undef</span>
directive as usual. This removes the referenced macro from the current region,
but leaves it unchanged in the original region, where it was defined initially.<br>
<br>
The argument of the <span class="preprocessor">#import</span> directive is <strong>not</strong>
subject to macro expansion before it is evaluated. </p>
<h3>Changes to the #ifdef, #ifndef directives and the operator defined()</h3>
<p>To fully support macro regions, the <span class="preprocessor">#ifdef</span>
and <span class="preprocessor">#ifndef</span> directives and the <span class="preprocessor">operator
defined()</span> may be used with qualified identifiers as its arguments too.
Therefor the following sample is completely wellformed (courtesy to Paul Mensonides):</p>
<pre> <span class="preprocessor"># ifndef</span> ::CHAOS_PREPROCESSOR::chaos::WSTRINGIZE_HPP
<span class="preprocessor"># region</span> ::CHAOS_PREPROCESSOR::chaos
<span class="preprocessor">#</span>
<span class="preprocessor"># define</span> WSTRINGIZE_HPP
<span class="preprocessor">#</span>
<span class="preprocessor"># include</span> <span class="copyright">&lt;chaos/experimental/cat.hpp&gt;</span>
<span class="preprocessor">#</span>
<span class="preprocessor">#</span> <span class="comment">// wstringize</span>
<span class="preprocessor">#</span>
<span class="preprocessor"># define</span> wstringize(...) \
chaos::primitive_wstringize(__VA_ARGS__) \
<span class="comment">/**/</span>
<span class="preprocessor">#</span>
<span class="preprocessor">#</span> <span class="comment">// primitive_wstringize</span>
<span class="preprocessor">#</span>
<span class="preprocessor"># define</span> primitive_wstringize(...) \
chaos::primitive_cat(L, #__VA_ARGS__) \
<span class="comment">/**/</span>
<span class="preprocessor">#</span>
<span class="preprocessor"># endregion</span>
<span class="preprocessor"># endif</span>
<span class="preprocessor"># import</span> ::CHAOS_PREPROCESSOR
chaos::wstringize(a,b,c) <span class="comment">// L&quot;a,b,c&quot;</span>
</pre>
<p>In the context of the <span class="preprocessor">#ifdef</span> and <span class="preprocessor">#ifndef</span>
directives and the <span class="preprocessor">operator defined()</span> a qualified
macro name is considered to be defined if:</p>
<ul>
<li>all regions referenced by the qualified name exist (opened at least once)
and</li>
<li>the referenced macro scope contains the definition of a macro with the given
name.</li>
</ul>
<h2><a name="new_alternative_tokens"></a>New alternative tokens</h2>
<p>Vesa Karvonen recently suggested on the <a href="http://aspn.activestate.com/ASPN/Mail/Message/boost/1618972">Boost
mailing list</a> the following addition to the preprocessor, which is implemented
by <tt>Wave</tt> in C++0x mode.</p>
<p>Consider the following example:</p>
<pre> <span class="preprocessor">#define</span> ID(x) x
ID( ( )
ID( a , b )
ID( ) )</pre>
<p>The macro expansion of the above preprocessor code does not produce the intended
result: </p>
<pre> ( a , b )</pre>
<p>The basic idea is that the keywords <tt>__lparen__</tt>, <tt>__rparen__</tt>
and <tt>__comma__</tt> could be used in place of <span class="literal">'('</span>,
<span class="literal">')'</span> and <span class="literal">','</span>, respectively.
The <br>
above example would now become:</p>
<pre> <span class="preprocessor">#define</span> ID(x) x
ID( __lparen__ )
ID( a __comma__ b )
ID( __rparen__ )</pre>
<p>and it would expand into:</p>
<pre> __lparen__ a __comma__ b __rparen__</pre>
<p>which would be recognized in translation phases after macro replacement as
equivalent to the token sequence:</p>
<pre> ( a , b )</pre>
<p>This trivial extension makes it an order of magnitude easier to generate C++
code using the C++ preprocessor.</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="class_reference_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="wave_driver.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
Copyright &copy; 2003 Paul Mensonides<br>
Copyright &copy; 2003 Vesa Karvonen<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span>
<p>&nbsp;</p>
</body>
</html>

114
doc/quickstart.html Normal file
View File

@@ -0,0 +1,114 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Quick Start</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 text="#000000" background="theme/bkd.gif">
<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">Quick
Start </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="introduction.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_context.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>The actual preprocessing itself is a highly configurable process, so obviously
you have to define a couple of parameters to&nbsp;control this process, such
as:</p>
<BLOCKQUOTE dir="ltr" style="MARGIN-RIGHT: 0px">
<P><STRONG><IMG id="IMG1" height="13" src="theme/bullet.gif" width="13"></STRONG>&nbsp;include
search pathes, which define, where to search for files to be included with
<tt>#include&nbsp;&lt;...&gt;</tt> and <tt>#include&nbsp;"..."</tt> directives<br>
<STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>which
macros to predefine and which of the predefined macros to undefine<br>
<STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>several
other options as for instance to control, whether to enable several extensions
to the C++ Standard (as for instance variadics and placemarkers) or not.</P>
</BLOCKQUOTE>
<p>You can access all these processing parameters through the <tt>boost::wave::context</tt>
object. So you have to instantiate one object of this type to use the <tt>Wave</tt>
library. For more information about the context template class please refer
to the class reference <a href="class_reference_context.html">here</a>. To instantiate
the <tt>boost::wave::context</tt> object you have to supply at least two template parameters:
the iterator type of the underlying input stream to use and the type of the
token to be returned from the preprocessing engine.</p>
<P dir="ltr">The main preprocessing iterators are not to be instantiated directly,
but should be generated through this context object too. </P>
<pre><span class="comment"> // The following preprocesses a given input file.
// Open the file and read it into a string variable</span>
<span class="keyword">std::ifstream</span> instream(<span class="string">&quot;input.cpp&quot;</span>);<br> <span class="keyword">std::string </span>input<span class="keyword">(
std::istreambuf_iterator&lt;char&gt;</span>(instream.rdbuf());
<span class="keyword">std::istreambuf_iterator&lt;char&gt;</span>());
<span class="comment">// The template wave::cpplexer::lex_token&lt;&gt; is the token
// type to be used by the Wave library.
// This token type is one of the central types throughout
// the library, because it is a template parameter to many
// of the public classes and templates and it is returned
// from the iterators itself.</span>
<span class="keyword">typedef</span> boost::wave::context&lt;<span class=keyword>std::string::iterator</span>,
boost::wave::cpplexer::lex_token&lt;&gt; &gt;
context_t;
<span class="comment">// The C++ preprocessor iterators shouldn't be constructed
// directly. These are to be generated through a
// wave::context&lt;&gt; object. Additionally this wave::context&lt;&gt;
// object is to be used to initialize and define different
// parameters of the actual preprocessing.
</span> context_t ctx(input.begin(), input.end(), <span class="string">&quot;input.cpp&quot;</span>);
context_t::iterator_t first = ctx.begin();
context_t::iterator_t last = ctx.end();
<span class="comment"> // The preprocessing of the input stream is done on the fly
// behind the scenes during the iteration over the
// context_t::iterator_t based stream. </span>
<span class="keyword">while</span> (first != last) {
<span class="keyword">std::cout</span> &lt;&lt; (*first).get_value();
++first;
}
</pre>
<P dir="ltr">The constructor of the <tt>boost::wave::context</tt> object can
take a pair of arbitrary iterator types (at least <tt>input_iterator</tt> type
iterators) to the input stream, from where should be read the data to be preprocessed.
The third parameter supplies a filename, which is used subsequently inside the
preprocessed tokens returned from the preprocessing to indicate the token position
inside the underlying input stream. Note though, that this filename is used
only as long no <tt>#include</tt> or <tt>#line</tt> directives are encountered,
which in turn will alter the current filename.</P>
<P dir="ltr">The iteration over the preprocessed tokens is relativly straight
forward. Just get the starting and the ending iterators from the context object
(maybe after initializing some include search paths) and you are done! The dereferencing
of the iterator will return the preprocessed tokens, which are generated on
the fly from the input stream. To get further information about the token type,
you may want to look <a href="class_reference_tokentype.html">here</a>.</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="introduction.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_context.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:41<!-- #EndDate -->
</span></body>
</html>

100
doc/references.html Normal file
View File

@@ -0,0 +1,100 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>References</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 text="#000000" background="theme/bkd.gif">
<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">References</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="acknowledgements.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><img src="theme/r_arr_disabled.gif" width="20" height="19" border="0"></td>
</tr>
</table>
<br>
<table width="90%" border="0" align="center">
<tr>
<td class="table_cells"> 1.</td>
<td class="table_cells"> <a name="iso_cpp"></a>ISO/IEC </td>
<td class="table_cells"><a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=INCITS%2FISO%2FIEC%2B14882%2D1998">&quot;Programming
languages - C++&quot;</a> <br>
ISO/IEC 14882:1998</td>
</tr>
<tr>
<td width="36" class="table_cells">2.</td>
<td width="236" class="table_cells"> <a name="iso_c"></a>INCITS/ISO/IEC </td>
<td width="520" class="table_cells"><a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=INCITS/ISO/IEC%2B9899-1999">&quot;Programming
languages - C&quot;</a> <br>
INCITS/ISO/IEC 9899:1999</td>
</tr>
<tr>
<td class="table_cells">3.</td>
<td class="table_cells"> <a name="re2c"></a>Peter Bumbulis and <br>
Donald D. Cowan</td>
<td class="table_cells"><a href="http://www.tildeslash.org/re2c/index.html">Re2c
V0.9.1 </a><br>
A tool for generating C-based recognizers from regular expressions</td>
</tr>
<tr>
<td class="table_cells">4.</td>
<td class="table_cells"><a name="spirit"></a>Joel de Guzman et.al.</td>
<td class="table_cells"><a href="http://spirit.sourceforge.net/">Spirit v1.6.0
documentation</a></td>
</tr>
<tr>
<td class="table_cells">5.</td>
<td class="table_cells"><a name="slex"></a>Daniel C. Nuffer</td>
<td class="table_cells"><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost/boost/libs/spirit/example/application/slex/">The
<tt>Spirit</tt> Slex example</a></td>
</tr>
<tr>
<td class="table_cells">6.</td>
<td class="table_cells"><a name="cpplexer"></a>Juan Carlos Arevalo-Baeza</td>
<td class="table_cells"><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/boost/boost/libs/spirit/example/application/cpp_lexer/">The
<tt>Spirit</tt> cpplexer example</a></td>
</tr>
<tr>
<td class="table_cells">7.</td>
<td class="table_cells"><a name="pp_lib"></a>Vesa Karvonen and <br>
Paul Mensonides </td>
<td class="table_cells"><a href="http://www.boost.org/libs/preprocessor/doc/index.html">The
Boost Library Preprocessor Subset for C/C++</a> </td>
</tr>
<tr>
<td class="table_cells">8.</td>
<td class="table_cells"><a name="boost"></a>boost.org</td>
<td class="table_cells"><a href="http://www.boost.org">The Boost Libraries
Documentation.</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="acknowledgements.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><img src="theme/r_arr_disabled.gif" width="20" height="19" border="0"></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>

93
doc/samples.html Normal file
View File

@@ -0,0 +1,93 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Introduction</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="theme/style.css" type="text/css">
</head>
<body text="#000000" background="theme/bkd.gif">
<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">Samples</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="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p dir="ltr">The <tt>Wave</tt> library contains several samples illustrating how to use the different features. This section describes these samples and its main characteristics. </p>
<h2>The <strong>cpp_tokens sample </strong></h2>
<p dir="ltr">The <tt>cpp_tokens</tt> sample dumps out the information contained within the tokens returned from the iterator supplied by the <tt>Wave</tt> library. It shows, how to use the <tt>Wave</tt> library in conjunction with custom lexer and custom token types. The lexer used within this sample is <tt>SLex</tt> <a href="references.html#slex">[5]</a> based, i.e. it <tt></tt> is feeded during runtime (at startup) with the token definitions (regular expressions) and generates a resulting DFA table. This table is used for token identification and is saved to disc afterwards to avoid the table generation process at the next program startup. The name of the file to which the DFA table is saved is <tt>wave_slex_lexer.dfa</tt>. </p>
<p dir="ltr">The main advantage of this <tt>SLex</tt> based lexer if compared to the default <tt>Re2C</tt> <a href="references.html#re2c">[3]</a> generated lexer is, that it provides not only the line information, where a particular token was recognized, but also the related column position. Otherwise the <tt>SLex</tt> based lexer is functionally fully compatible to the <tt>Re2C</tt> based one, i.e. you always may switch your application to use it, if you additionally need to get the column information back from the preprocessing. </p>
<p dir="ltr">Since no additional command line parameters are supported by this sample, it won't work well with include files, which aren't located in the same directory as the inspected input file. The command line syntax is straight forward:</p>
<pre> cpp_tokens input_file</pre>
<h2 dir="ltr">The list_includes sample </h2>
<p dir="ltr">The <tt>list_includes</tt> sample shows how the <tt>Wave</tt> library may be used to generate a include file dependency list for a particular input file. It completely depends on the default library configuration. The command line syntax for this sample is given below: </p>
<pre> Usage: list_includes [options] file ...:
-h [ --help ] : print out program usage (this message)
-v [ --version ] : print the version number
-I [ --path ] dir : specify additional include directory
-S [ --syspath ] dir : specify additional system include directory
</pre>
<p dir="ltr">Please note though, that this sample will output only those include file names, which are visible to the preprocessor, i.e. given the following code snippet, only one of the two include file directives is triggered during preprocess<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate -->ned</span><span class="special">(</span>INCLUDE_FILE_A<span class="special">)</span>
<span class="preprocessor"> #include</span> <span class="literal">&quot;file_a.h&quot;</span>
<span class="preprocessor"> #else</span>
<span class="preprocessor"> #include</span> <span class="literal">&quot;file_b.h&quot;</span>
<span class="preprocessor"> #endif</span>
</pre>
<p dir="ltr">Besides on the <tt>Wave</tt> library, this sample depends on the <tt>program_options</tt> library from <a href="mailto:ghost@cs.msu.su">Vladimir Prus</a>, recently adopted to Boost. Since this library isn't contained yet within Boost, you'll have to download it separately from <a href="http://boost-sandbox.sourceforge.net/program_options/">here</a>. It integrates well into the Boost build process, so no additional tools needed to use it with the Wave driver.</p>
<h2 dir="ltr">The wave sample</h2>
<p dir="ltr">Because of its general usefulness the <tt>wave</tt> sample isn't located in the sample directory of the library, but inside the tools directory of Boost. The wave sample is usable as a full fledged preprocessor executable
on top of any other C++ compiler. It outputs the textual representation of the
preprocessed tokens generated from a given input file. It is described in more details <a href="wave_driver.html">here</a>. </p>
<h2 dir="ltr">The waveidl sample </h2>
<p dir="ltr">The main point of the waveidl sample is to show, how a completely independent lexer type may be used in conjunction with the default token type of the <tt>Wave</tt> library. The lexer used in this sample is supposed to be used for an IDL language based preprocessor. It is based on the <tt>Re2C</tt> tool too, but recognizes a different set of tokens as the default C++ lexer contained within the <tt>Wave</tt> library. So this lexer does not recognize any keywords (except <tt>true</tt> and <tt>false</tt>, which are needed by the preprocessor itself). This is needed because there exist different IDL languages, where identifiers of one language may be keywords of others. Certainly this implies to postpone keyword identification after the preprocessing, but allows to use <tt>Wave</tt> for all of the IDL derivatives. </p>
<p dir="ltr">It is only possible to use the <tt>Wave</tt> library to write an IDL preprocessor, because the token sets for both languages are very similar. The tokens to be recognized by the <tt>waveidl</tt> IDL language preprocessor is nearly a complete subset of the full C++ token set. </p>
<p dir="ltr">The command line syntax usable for this sample is shown below:</p>
<pre> Usage: waveidl [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
-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
</pre>
<p dir="ltr">Besides on the <tt>Wave</tt> library, this sample depends on the <tt>program_options</tt> library from <a href="mailto:ghost@cs.msu.su">Vladimir Prus</a>, recently adopted to Boost. Since this library isn't contained yet within Boost, you'll have to download it separately from <a href="http://boost-sandbox.sourceforge.net/program_options/">here</a>. It integrates well into the Boost build process, so no additional tools needed to use it with the <tt>waveidl</tt> sample. </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="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) </font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate -->
</span>
<p>&nbsp;</p>
</body>
</html>
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate --><!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate -->

128
doc/supported_pragmas.html Normal file
View File

@@ -0,0 +1,128 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Supported Pragma Directives</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">Supported
Pragma Directives</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="predefined_macros.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="macro_expansion_process.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>The Wave preprocessor library supports a couple of specific <tt>#pragma</tt>
directives, which may be used to control some of the library features. All directives
described here are usable as conventional <tt>#pragma</tt> directives and as
<tt>operator&nbsp;_Pragma</tt> (if variadics are enabled). So for instance the
following directives are functionally identical:</p>
<pre> #pragma wave trace(enable) </pre>
<p>and </p>
<pre> _Pragma(&quot;wave trace(enable)&quot;)</pre>
<p>All <tt>Wave</tt> specific pragma's must have the general form <tt>'wave option[(value)]'</tt>,
where <tt>'wave'</tt> is the specific keyword, <tt>'option'</tt> is the concrete
pragma functionality to trigger and <tt>'value'</tt> is an optional value to
be supplied to the <tt>'option'</tt> functionality. The following table lists
all possible pragma functions supported by the <tt>Wave</tt> library. </p>
<table width="77%" border="0" align="center">
<tr>
<td colspan="4"> <p class="table_title">Supported pragma's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%">pragma option</p></td>
<td> <p class="toc_title" width="28%">pragma value</p></td>
<td> <p class="toc_title" width="36%">description</p></td>
<td> <p class="toc_title" width="36%">supported by</p></td>
</tr>
<tr>
<td class="table_cells" width="19%"> <p>trace</p></td>
<td class="table_cells" width="18%"> <p>enable/on/1<br>
disable/off/0</p></td>
<td class="table_cells" width="43%"><p>Enable or disable the tracing of the
macro expansion process. This is needed, even if there is given the --trace
command line option, because the trace output is generated only, if there
is at least one trace(enable) pragma found.</p></td>
<td class="table_cells" width="20%"><p>Wave library</p></td>
</tr>
<tr>
<td class="table_cells"><p>stop</p></td>
<td class="table_cells"><p>message</p></td>
<td class="table_cells"><p>Stop the execution of <tt>Wave</tt> and print out
the given message. This is very helpful for direct debugging purposes.</p></td>
<td class="table_cells"><p>Wave library</p></td>
</tr>
<tr>
<td class="table_cells"><p>system</p></td>
<td class="table_cells"><p>command</p></td>
<td class="table_cells"><p>Try to spawn the 'command' as a new operating system
command and intercept the generated stdout and stderr. The stdout output
of this command (if any) is retokenized and used as the replacement text
for the whole pragma, the stderr output is ignored. The command is considered
to be successful, if/when the return value is zero, otherwise an error
is reported. <br>
</p></td>
<td class="table_cells"><p>Wave library</p></td>
</tr>
<tr>
<td class="table_cells"><p>timer</p></td>
<td class="table_cells"><p> restart/0<br>
&lt;no value&gt; <br>
suspend<br>
resume </p></td>
<td class="table_cells"><p>The value <tt>restart</tt> set the current elapsed
time to 0 and restarts the timer.<br>
If no value is provided, the current elpsed time is printed to the std::cerr
stream.<br>
The values <tt>suspend</tt> and <tt>resume</tt> allow to temporarily stop
the timing.</p></td>
<td class="table_cells"><p>Wave driver</p></td>
</tr>
</table>
<p>All pragma's not listed here but flagged as <tt>'wave'</tt> are reported as
errors. The handling of all remaining pragma's depends on the compilation constant
<code><tt>WAVE_RETURN_PRAGMA_DIRECTIVES</tt></code>, which allows to specify,
if those pragmas are left unchanged in the output stream or not. Please note,
that the operator _Pragma variant is always subject to full preprocessing, before
the pragma itself is evaluated. The #pragma variant is subject to preprocessing
only, if the <code><tt>WAVE_PREPROCESS_PRAGMA_BODY</tt></code> compilation constant
was specified during compilation. For more information about the possible compilation
constants look <a href="compiletime_config.html">here</a>.</p>
<p>Additionally the Wave preprocessor supports the <tt>#pragma once</tt> directive,
which specifies that the file, in which the pragma resides, will be included
(opened) only once by the compiler in a build. This may be used to optimize
the preprocessing of larger compilation units, which include a lot of files. Note though, that the #pragma once directive is supported only, if the compile time constant <tt>WAVE_SUPPORT_PRAGMA_ONCE</tt> was given during compilation of the library</span>.</p>
<p>It is fairly easy to implement your own <tt>#pragma wave ... </tt> directives. All you have to do is to implement your own <tt>interpret_pragma</tt> function (see <a href="class_reference_tracepolicy.html#interpret_pragma">here</a>) which should the handle additional directives. For an example of how to do it, you may have a look at the Wave driver application, which implements the <tt>#pragma wave timer()</tt> directive with the help of a supplied <tt>interpret_pragma</tt> function. </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="predefined_macros.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="macro_expansion_process.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:48<!-- #EndDate -->
</span>
<p>&nbsp;</p>
</body>
</html>

BIN
doc/theme/bkd.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.0 KiB

BIN
doc/theme/bkd2.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 843 B

BIN
doc/theme/bullet.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 152 B

BIN
doc/theme/l_arr.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 146 B

BIN
doc/theme/l_arr_disabled.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 B

BIN
doc/theme/r_arr.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 147 B

BIN
doc/theme/r_arr_disabled.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 B

175
doc/theme/style.css vendored Normal file
View File

@@ -0,0 +1,175 @@
body
{
background-image: url(bkd.gif);
background-color: #FFFFFF;
margin: 1em 2em 1em 2em;
}
h1 { font-family: Verdana, Arial, Helvetica, sans-serif; font-weight: bold; text-align: left; }
h2 { font: 140% sans-serif; font-weight: bold; text-align: left; }
h3 { font: 120% sans-serif; font-weight: bold; text-align: left; }
h4 { font: bold 100% sans-serif; font-weight: bold; text-align: left; }
h5 { font: italic 100% sans-serif; font-weight: bold; text-align: left; }
h6 { font: small-caps 100% sans-serif; font-weight: bold; text-align: left; }
pre
{
border-top: gray 1pt solid;
border-right: gray 1pt solid;
border-left: gray 1pt solid;
border-bottom: gray 1pt solid;
padding-top: 2pt;
padding-right: 2pt;
padding-left: 2pt;
padding-bottom: 2pt;
display: block;
font-family: "courier new", courier, mono;
background-color: #eeeeee; font-size: small
}
code
{
font-family: "Courier New", Courier, mono;
font-size: small
}
tt
{
display: inline;
font-family: "Courier New", Courier, mono;
color: #000099;
font-size: small
}
p
{
text-align: justify;
font-family: Georgia, "Times New Roman", Times, serif
}
ul
{
list-style-image: url(bullet.gif);
font-family: Georgia, "Times New Roman", Times, serif
}
ol
{
font-family: Georgia, "Times New Roman", Times, serif
}
a
{
font-weight: bold;
color: #003366;
text-decoration: none;
}
a:hover { color: #8080FF; }
.literal { color: #666666; font-style: italic}
.keyword { color: #000099}
.identifier {}
.comment { font-style: italic; color: #990000}
.special { color: #800040}
.preprocessor { color: #990099}
.string { font-style: italic; color: #666666}
.copyright { color: #666666; font-size: small}
.white_bkd { background-color: #FFFFFF}
.dk_grey_bkd { background-color: #999999}
.quotes { color: #666666; font-style: italic; font-weight: bold}
.note_box
{
display: block;
border-top: gray 1pt solid;
border-right: gray 1pt solid;
border-left: gray 1pt solid;
border-bottom: gray 1pt solid;
padding-right: 12pt;
padding-left: 12pt;
padding-bottom: 12pt;
padding-top: 12pt;
font-family: Arial, Helvetica, sans-serif;
background-color: #E2E9EF;
font-size: small; text-align: justify
}
.table_title
{
background-color: #648CCA;
font-family: Verdana, Arial, Helvetica, sans-serif; color: #FFFFFF;
font-weight: bold
; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px
}
.table_cells
{
background-color: #E2E9EF;
font-family: Geneva, Arial, Helvetica, san-serif;
font-size: small
; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px
}
.toc
{
DISPLAY: block;
background-color: #E2E9EF
font-family: Arial, Helvetica, sans-serif;
border-top: gray 1pt solid;
border-left: gray 1pt solid;
border-bottom: gray 1pt solid;
border-right: gray 1pt solid;
padding-top: 24pt;
padding-right: 24pt;
padding-left: 24pt;
padding-bottom: 24pt;
}
.toc_title
{
background-color: #648CCA;
padding-top: 4px;
padding-right: 4px;
padding-bottom: 4px;
padding-left: 4px;
font-family: Geneva, Arial, Helvetica, san-serif;
color: #FFFFFF;
font-weight: bold
}
.toc_cells
{
background-color: #E2E9EF;
padding-top: 4px;
padding-right: 4px;
padding-bottom: 4px;
padding-left: 4px;
font-family: Geneva, Arial, Helvetica, san-serif;
font-size: small
}
div.logo
{
float: right;
}
.toc_cells_L0 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small }
.toc_cells_L1 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 44px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small }
.toc_cells_L2 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 88px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small }
.toc_cells_L3 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 122px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small }
.toc_cells_L4 { background-color: #E2E9EF; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 166px; font-family: Geneva, Arial, Helvetica, san-serif; font-size: small }
.updated {
font-size: x-small;
color: #666666;
font-style: italic;
}

BIN
doc/theme/u_arr.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 170 B

BIN
doc/theme/uc.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 919 B

BIN
doc/theme/wave.gif vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 938 B

972
doc/token_ids.html Normal file
View File

@@ -0,0 +1,972 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Token Identifiers</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
Token Identifiers</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="class_reference_tokentype.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_fileposition.html"><img src="theme/r_arr.gif" width="20" height="19" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="token_ids.html#literal_tokens">Table of literal token identifiers</a><br>
<a href="token_ids.html#whitespace_tokens">Table of white token identifiers</a><br>
<a href="token_ids.html#keyword_tokens">Table of keyword token identifiers</a><br>
<a href="token_ids.html#operator_tokens">Table of operator token identifiers</a><br>
<a href="token_ids.html#preprocessor_tokens">Table of preprocessor token identifiers</a></p>
</blockquote>
<p>The following tables contain all those tokens, which should be recognized by
a C++ lexer, which is to be used in conjunction with the <tt>Wave</tt> preprocessing
engine. The tokens are grouped into categories to simplify some internal logic
and eventually the driver programs. The token identifiers are defined as an
<tt>enum</tt>, and it is recommended to reuse this definition for your own lexer
implementations.</p>
<p>Note though, that the preprocessor engine does some token transformation, so
that not all of the listet here token identifiers may occur inside tokens, returned
from the preprocessing iterator.</p>
<a name="literal_tokens"></a>
<table width="70%" border="0" align="center">
<tr>
<td colspan="3"> <p class="table_title">List of literal token id's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%" >Token identifier</p></td>
<td> <p class="toc_title" width="28%" >Token category</p></td>
<td> <p class="toc_title" width="36%" >Token value</p></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CHARLIT  </p></td>
<td class="table_cells" width="31%"> <p>CharacterLiteralTokenType</p></td>
<td class="table_cells" width="29%"><p><code>'a', '\t', '\u0057'</code></p></td>
</tr>
<tr>
<td class="table_cells" > <p>T_FLOATLIT </p></td>
<td class="table_cells" > <p>FloatingLiteralTokenType</p></td>
<td class="table_cells" ><code>-1.23456e78</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_IDENTIFIER </p></td>
<td class="table_cells" > <p>IdentifierTokenType</p></td>
<td class="table_cells" ><code> C++ identifier</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_OCTALINT </p></td>
<td class="table_cells" > <p>IntegerLiteralTokenType</p></td>
<td class="table_cells" ><code>007</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_DECIMALINT </p></td>
<td class="table_cells" > <p>IntegerLiteralTokenType</p></td>
<td class="table_cells" ><code>10</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_HEXAINT </p></td>
<td class="table_cells" > <p>IntegerLiteralTokenType</p></td>
<td class="table_cells" ><code>0x1234</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_INTLIT </p></td>
<td class="table_cells" > <p>IntegerLiteralTokenType</p></td>
<td class="table_cells" ><code>T_OCTALINT, T_DECIMALINT or T_HEXAINT</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_STRINGLIT </p></td>
<td class="table_cells" > <p>StringLiteralTokenType</p></td>
<td class="table_cells" ><code>&quot;abc&quot;</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_FALSE </p></td>
<td class="table_cells" > <p>BoolLiteralTokenType</p></td>
<td class="table_cells" ><code>false</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TRUE </p></td>
<td class="table_cells" width="31%" > <p>BoolLiteralTokenType</p></td>
<td class="table_cells" width="29%" ><code>true</code></td>
</tr>
</table>
<br>
<a name="whitespace_tokens"></a>
<table width="70%" border="0" align="center">
<tr>
<td colspan="3"> <p class="table_title">List of whitespace token id's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%" >Token identifier</p></td>
<td> <p class="toc_title" width="28%" >Token category</p></td>
<td> <p class="toc_title" width="36%" >Token value</p></td>
</tr>
<tr>
<td class="table_cells" width="40%"> <p>T_ANY </p></td>
<td class="table_cells" width="31%"> <p>UnknownTokenType</p></td>
<td class="table_cells" width="29%"> <p><code>any value not matched otherwise</code></p></td>
</tr>
<tr>
<td class="table_cells" > <p>T_CCOMMENT </p></td>
<td class="table_cells" > <p>WhiteSpaceTokenType</p></td>
<td class="table_cells" > <p><code>/* ... */</code></p></td>
</tr>
<tr>
<td class="table_cells" > <p>T_CPPCOMMENT </p></td>
<td class="table_cells" > <p>WhiteSpaceTokenType</p></td>
<td class="table_cells" ><code>// ... \n</code></td>
</tr>
<tr>
<td class="table_cells" > <p>T_SPACE </p></td>
<td class="table_cells" > <p>WhiteSpaceTokenType</p></td>
<td class="table_cells" > <p>blank or '\t'</p></td>
</tr>
<tr>
<td class="table_cells" > <p>T_SPACE2 </p></td>
<td class="table_cells" > <p>WhiteSpaceTokenType</p></td>
<td class="table_cells" ><code>'\v' or '\f'</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_EOF </p></td>
<td class="table_cells" width="31%" > <p>EOFTokenType</p></td>
<td class="table_cells" width="29%" ><code>end of input</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CONTLINE </p></td>
<td class="table_cells" width="31%" > <p>EOLTokenType</p></td>
<td class="table_cells" width="29%" ><code>'\\' followed by '\n'</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NEWLINE </p></td>
<td class="table_cells" width="31%" > <p>EOLTokenType</p></td>
<td class="table_cells" width="29%" ><code>'\n'</code></td>
</tr>
</table>
<br>
<br>
<a name="keyword_tokens"></a>
<table width="70%" border="0" align="center">
<tr>
<td colspan="3"> <p class="table_title">List of keyword token id's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%" >Token identifier</p></td>
<td> <p class="toc_title" width="28%" >Token category</p></td>
<td> <p class="toc_title" width="36%" >Token value</p></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ASM </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>asm</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_AUTO </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>auto</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_BOOL </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>bool</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_BREAK </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>break</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CASE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>case</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CATCH </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>catch</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CHAR </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>char</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CLASS </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>class</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CONST </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>const</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CONSTCAST </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>const_cast</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_CONTINUE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>continue</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DEFAULT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>default</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DEFINED </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>defined</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DELETE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>delete</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DO </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>do</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DOUBLE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>double</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DYNAMICCAST </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>dynamic_cast</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ELSE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>else</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ENUM </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>enum</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_EXPLICIT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>explicit</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_EXPORT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>export</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_EXTERN </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>extern</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_FLOAT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>float</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_FOR </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>for</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_FRIEND </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>friend</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_GOTO </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>goto</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_IF </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>if</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_INLINE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>inline</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_INT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>int</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LONG </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>long</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_MUTABLE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>mutable</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NAMESPACE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>namespace</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NEW </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>new</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_OPERATOR </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>operator</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PRIVATE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>private</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PROTECTED </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>protected</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PUBLIC </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>public</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_REGISTER </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>register</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_REINTERPRETCAST </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>reinterpret_cast</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RETURN </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>return</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SHORT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>short</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SIGNED </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>signed</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SIZEOF </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>sizeof</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_STATIC </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>static</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_STATICCAST </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>static_cast</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_STRUCT </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>struct</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SWITCH </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>switch</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TEMPLATE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>template</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_THIS </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>this</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_THROW </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>throw</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TRY </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>try</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TYPEDEF </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>typedef</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TYPEID </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>typeid</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_TYPENAME </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>typename</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_UNION </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>union</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_UNSIGNED </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>unsigned</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_USING </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>using</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_VIRTUAL </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>virtual</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_VOID </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>void</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_VOLATILE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>volatile</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_WCHART </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>wchar_t</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_WHILE </p></td>
<td class="table_cells" width="31%" > <p>KeywordTokenType</p></td>
<td class="table_cells" width="29%" ><code>while</code></td>
</tr>
</table>
<br>
<a name="operator_tokens"></a>
<table width="70%" border="0" align="center">
<tr>
<td colspan="3"> <p class="table_title">List of operator token id's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%" >Token identifier</p></td>
<td> <p class="toc_title" width="28%" >Token category</p></td>
<td> <p class="toc_title" width="36%" >Token value</p></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_AND </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&amp;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ANDAND </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&amp;&amp;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ANDASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&amp;=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_OR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>|</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ORASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>|=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_XOR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>^</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_XORASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>^=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COMMA </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>,</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COLON </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>:</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DIVIDE </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>/</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DIVIDEASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>/=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DOT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>.</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_DOTSTAR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>.*</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ELLIPSIS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>...</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_EQUAL </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>==</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_GREATER </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_GREATEREQUAL </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&gt;=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACE </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>{</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LESS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LESSEQUAL </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTPAREN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>(</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACKET </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>[</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_MINUS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>-</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_MINUSASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>-=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_MINUSMINUS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>--</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PERCENT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>%</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PERCENTASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>%=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NOT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>!</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NOTEQUAL </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>!=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_OROR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>||</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PLUS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>+</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PLUSASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>+=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PLUSPLUS </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>++</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ARROW </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>-&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ARROWSTAR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>-&gt;*</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_QUESTION_MARK </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>?</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACE </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>}</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTPAREN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>)</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACKET </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>]</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COLON_COLON </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>::</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SEMICOLON </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SHIFTLEFT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;&lt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SHIFTLEFTASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;&lt;=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SHIFTRIGHT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&gt;&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_SHIFTRIGHTASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>&gt;&gt;=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_STAR </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>*</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COMPL </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>~</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_STARASSIGN </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>*=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND_POUND </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>##</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType</p></td>
<td class="table_cells" width="29%" ><code>#</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_AND_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>bitand</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ANDASSIGN_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>and_eq</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_OR_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>or</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_ORASSIGN_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>or_eq</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_XOR_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>xor</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_XORASSIGN_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>xor_eq</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACE_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;%</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACKET_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>&lt;:</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NOT_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>not</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_NOTEQUAL_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>not_eq</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACE_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>%&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACKET_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>:&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COMPL_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>compl</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND_POUND_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>%:%:</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND_ALT </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| AltTokenType</p></td>
<td class="table_cells" width="29%" ><code>%:</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_OR_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??!</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_XOR_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??'</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACE_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??&lt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_LEFTBRACKET_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??(</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACE_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_RIGHTBRACKET_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??)</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_COMPL_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??-</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND_POUND_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??=??=</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_POUND_TRIGRAPH </p></td>
<td class="table_cells" width="31%" > <p>OperatorTokenType&nbsp;| TriGraphTokenType</p></td>
<td class="table_cells" width="29%" ><code>??=</code></td>
</tr>
</table>
<p><br>
<a name="preprocessor_tokens"></a> The preprocessor tokens listet in the following
table are returned by the C++ lexer only. The preprocessor naturally acts on
these tokens and they are not returned by dereferencing the preprocessing iterators.</p>
<table width="70%" border="0" align="center">
<tr>
<td colspan="3"> <p class="table_title">List of preprocessor token id's</p></td>
</tr>
<tr>
<td> <p class="toc_title" width="36%" >Token identifier</p></td>
<td> <p class="toc_title" width="28%" >Token category</p></td>
<td> <p class="toc_title" width="36%" >Token value</p></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_DEFINE </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#define</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_IF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#if</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_IFDEF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#ifdef</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_IFNDEF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#ifndef</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_ELSE </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#else</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_ELIF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#elif</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_ENDIF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#endif</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_ERROR </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#error</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_LINE </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#line</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_PRAGMA </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#pragma</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_UNDEF </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#undef</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_WARNING </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#warning</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_INCLUDE </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#include &quot;...&quot;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_QHEADER </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#include &lt;...&gt;</code></td>
</tr>
<tr>
<td class="table_cells" width="40%" > <p>T_PP_HHEADER </p></td>
<td class="table_cells" width="31%" > <p>PPTokenType</p></td>
<td class="table_cells" width="29%" ><code>#include ...</code></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="class_reference_tokentype.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_fileposition.html"><img src="theme/r_arr.gif" width="20" height="19" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>

162
doc/tracing_facility.html Normal file
View File

@@ -0,0 +1,162 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Tracing Facility</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
Tracing Facility</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="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>If you ever had the need to debug a macro expansion you had to discover, that
your tools provide only little or no support for this task. For this reason
the <i>Wave</i> library got a tracing facility, which allows to get selectively
some information about the expansion of a certain macro or several macros. </p>
<p>The tracing of macro expansions generates a possibly huge amount of information,
so it is recommended, that you explicitely enable/disable the tracing for the
macro in question only. This may be done with the help of a special, <tt>Wave</tt>
specific #pragma:</p>
<pre><span class="preprocessor"> #pragma</span> wave trace(enable) <span class="comment">// enable the tracing</span>
<span class="comment">// the macro expansions here will be traced</span>
<span class="comment">// ...</span>
<span class="preprocessor"> #pragma</span> wave trace(disable) <span class="comment">// disable the tracing</span></pre>
<p>In C99 mode or when specifying the <tt>--variadics</tt> command line option
you may additionally use the <tt>operator&nbsp;_Pragma()</tt> variant to enable/disable
the tracing output:</p>
<pre><span class="preprocessor"> #define</span> CONCAT(x, y) \
<span class="preprocessor">_Pragma</span>(<span class="string">&quot;wave trace(enable)&quot;</span>) \
x \
<span class="preprocessor">_Pragma</span>(<span class="string">&quot;wave trace(disable)&quot;</span>) \
<span class="keyword">##</span> y</pre>
<p>This way you have the possibility to enable the tracing during the expansion
of a part of a macro only. In the sample shown there is traced the expansion
of the macro argument <tt>'x'</tt> only. Note, that the <tt>operator _Pragma()</tt>
directives expand to nothing inside the macro expansion result.</p>
<p>To see, what the <tt>Wave</tt> driver generates while expanding a simple macro,
let's have a look at the tracing output for the following example:</p>
<pre ><span class="comment"> // test.cpp</span>
<span class="preprocessor"> #define</span> X(x) x<br><span class="preprocessor"> #define</span> Y() 2<br><span class="preprocessor"> #define</span> CONCAT_(x, y) x <span class="keyword">##</span> y
<span class="preprocessor"> #define</span> CONCAT(x, y) CONCAT_(x, y)
<span class="preprocessor"> #pragma</span> wave trace(enable)
<span class="comment"> // this macro expansion is to be traced</span>
CONCAT(X(1), Y()) <span class="comment">// should expand to 12</span>
<span class="preprocessor"> #pragma</span> wave trace(disable)</pre>
<p>When preprocessed with <tt>'wave -t test.trace test.cpp'</tt> the <tt>Wave</tt>
driver generates a file <tt>test.trace</tt>, which contains (without the line
numbers in front of the lines):</p>
<pre> 1: test.cpp(8): CONCAT(X(1), Y())
2: test.cpp(5): see macro definition: CONCAT(x, y)
3: invoked with
4: [
5: x = X(1)
6: y = Y()
7: ]
8: [
9: test.cpp(2): see macro definition: X(x)
10: invoked with
11: [
12: x = 1
13: ]
14: [
15: 1
16: rescanning
17: [
18: 1
19: ]
20: ]
21: test.cpp(3): see macro definition: Y()
22: [
23: 2
24: rescanning
25: [
26: 2
27: ]
28: ]
29: CONCAT_(1, 2)
30: rescanning
31: [
32: test.cpp(4): see macro definition: CONCAT_(x, y)
33: invoked with
34: [
35: x = 1
36: y = 2
37: ]
38: [
39: 12
40: rescanning
41: [
42: 12
43: ]
44: ]
45: 12
46: ]
47: ]
</pre>
<p>The generated trace output is very verbose, but allows to follow every step
of the actual macro expansion process. The first line in this tracing example
contains the reference to the position, from where the macro expansion was initiated.
Additionally the following information is contained for every single macro expansion:</p>
<ul>
<li>The reference to the position, where the macro to expand was defined first
(see lines 2, 9, 21 and 32).</li>
<li>The real parameters supplied for this macro expansion (see lines 3, 10 and
33), this information is traced inside the <tt>invoked with</tt> block, where
the corresponding formal and actual parameters are listed.</li>
<li>The expansion of the given arguments (if any and if these are defined as
macros). This repeats the full tracing information for the argument macro
expansion, only intended by one level. Note though, that the macro expansion
of the actual arguments is traced, regardless of the fact, if this argument
is really to be inserted into the replacement list only after its expansion
or as it was initially supplied (see C++ Standard [16.3.1.1]: &quot;A parameter
in the replacement list, unless preceded by a <tt>#</tt> or <tt>##</tt> preprocessing
token or followed by a <tt>##</tt> preprocessing token, is replaced by the
corresponding argument after all macros contained therein have been expanded&quot;
<a href="references.html#iso_cpp">[1]</a>). </li>
<li>The result of the argument substitution (see lines 15, 23, 29 and 39), i.e.
the substituted replacement list.</li>
<li>The rescanning process, which again includes the full subsequent macro expansion
process of all found macros (see C++ Standard [16.3.4.1]: &quot;After all
parameters in the replacement list have been substituted, the resulting preprocessing
token sequence is rescanned with all subsequent preprocessing tokens of the
source file for more macro names to replace.&quot; <a href="references.html#iso_cpp">[1]</a>).</li>
<li>The result of the actual macro expansion (this is the last line inside the
corresponding rescanning block - see lines 18, 26, 42 and 45).</li>
</ul>
<p>Every found macro to expand will add an additional indentation level inside
the trace output.</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="wave_driver.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright &copy; 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Sunday, January 4, 2004 0:17<!-- #EndDate -->
</span>
</body>
</html>
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->

215
doc/wave_driver.html Normal file
View File

@@ -0,0 +1,215 @@
<!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="30"><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 nearly all 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 [-]
--timer output overall elapsed computing time
--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.<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 18:56<!-- #EndDate -->-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">--timer</p>
<blockquote>
<p dir="ltr">Enable to track the overall elapsed computing time required for
the given input file. The elapsed time is printed to stdout after the compilation
is completed.</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>
<p dir="ltr">Besides on the <tt>Wave</tt> library, this sample depends on the <tt>program_options</tt> library from <a href="mailto:ghost@cs.msu.su">Vladimir Prus</a>, recently adopted to Boost. Since this library isn't contained yet within Boost, you'll have to download it separately from <a href="http://boost-sandbox.sourceforge.net/program_options/">here</a>. It integrates well into the Boost build process, so no additional tools needed to use it with the Wave 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="30"><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-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to the Boost Software
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
</font> </p>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 18:56<!-- #EndDate -->
</span></body>
</html>