Boost logo

Boost-Commit :

From: hartmut.kaiser_at_[hidden]
Date: 2008-07-29 21:42:39


Author: hkaiser
Date: 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
New Revision: 47875
URL: http://svn.boost.org/trac/boost/changeset/47875

Log:
Wave: More documentation updates
Removed:
   branches/release/libs/wave/doc/class_ref_ctxpolicy_depr.html
Text files modified:
   branches/release/libs/wave/doc/class_reference_context.html | 887 +++++++++++----------------------------
   branches/release/libs/wave/doc/class_reference_ctxpolicy.html | 4
   branches/release/libs/wave/doc/compiletime_config.html | 8
   branches/release/libs/wave/doc/quickstart.html | 10
   branches/release/libs/wave/doc/wave_driver.html | 6
   branches/release/libs/wave/index.html | 183 ++++----
   6 files changed, 359 insertions(+), 739 deletions(-)

Deleted: branches/release/libs/wave/doc/class_ref_ctxpolicy_depr.html
==============================================================================
--- branches/release/libs/wave/doc/class_ref_ctxpolicy_depr.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
+++ (empty file)
@@ -1,342 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-<title>The Context 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
- Context Policy (depreciated interface) </font></b></font></td>
- <td width="96"></td>
- </tr>
-</table>
-<br>
-<table border="0">
- <tr>
- <td width="10"></td>
- <td width="30"></td>
- <td width="30"></td>
- <td width="30"></td>
- </tr>
-</table>
-<blockquote>
- <p>Introduction<br>
- <a href="class_reference_ctxpolicy.html#header_synopsis">Header 'wave/preprocessing_hooks.hpp'
- synopsis</a><br>
- Member functions</p>
-</blockquote>
-<h2><b><a name="introduction"></a>Introduction</b></h2>
-<p>Please note that the following description relates to a depreciated interface as it was used by default up to Boost V1.34.x. For the new interface please refer to The Context Policy. You can still force to use this older interface by defining the <tt>BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS</tt> preprocessing constant as outlined in the <a href="compiletime_config.html">Compile
-Time Configuration</a> section. By default the new interface is used starting Boost V1.35.0, while the older one is used by default otherwise. </p>
-<p>The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever</p>
-<ul>
- <li>a preprocessor directive has been recognized, </li>
- <li>a token is about to be returned from the preprocessor, </li>
- <li>a macro get's defined or undefined, </li>
- <li>a macro has been expanded or rescanned,</li>
- <li>an include file has been opened or left, </li>
- <li>a conditional expression was evaluated,</li>
- <li>a token has to be skipped because it is contained in a non-evaluated conditional block, </li>
- <li> a pragma of the form <tt>'wave option[(value)]'</tt> has been recognised. </li>
-</ul>
-<p>This policy type is used as a template parameter to the boost::wave::context<>
- object, where the default policy provides empty hook functions only.</p>
-<h2><a name="header_synopsis"></a>Header wave/preprocessing_hooks.hpp
- synopsis</h2>
-<pre>
-<span class="keyword">namespace</span> boost {
-<span class="keyword">namespace</span> wave {
-<span class="keyword">namespace</span> context_policies {
-
- <span class="keyword">struct</span> default_preprocessing_hooks {
-
- <span class="comment">// general hook functions</span>
- <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> found_directive(TokenT <span class="keyword">const </span>&amp;directive);<br>
- <span class="comment">// test, whether a given token may be skipped</span><br> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT&gt;
- <span class="keyword">bool</span> may_skip_whitespace (ContextT <span class="keyword">const</span>&amp; ctx,
- TokenT &amp;token, <span class="keyword">bool</span> &amp;skipped_newline);<br>
- </span><span class="comment">// Conditional compilation</span><span class="keyword">
- template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;<br> <span class="keyword">bool</span> evaluated_conditional_expression(ContainerT <span class="keyword">const</span>&amp; expression, <br> <span class="keyword">bool</span> expression_value);<br>
- <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> skipped_token(TokenT <span class="keyword">const</span></span>&amp; token);<br>
- <span class="comment">// macro expansion tracing</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> 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);
-
- <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);
-
- <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);
-
- <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);
-
- <span class="comment">// include file tracing functions</span>
- <span class="keyword">void</span> found_include_directive(std::string <span class="keyword">const</span> &amp;filename,
- <span class="keyword">bool</span> include_next);
-
- <span class="keyword">void </span>opened_include_file(std::string <span class="keyword">const</span> &amp;relname,
- std::string const&amp; absname,
- std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
-
- <span class="keyword">void</span> returning_from_include_file();
-
- <span class="comment">// interpretation of #pragma's of the form </span>
- <span class="comment">// 'wave option[(value)]'</span>
- <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;
- bool interpret_pragma(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option,
- ContainerT <span class="keyword">const</span> &amp;values,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;pragma_token);
-
- <span class="comment">// macro definition hooks</span>
- <span class="keyword">template</span> &lt;
- <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT
- &gt;
- <span class="keyword">void</span> defined_macro(TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">bool</span> is_functionlike,
- ParametersT <span class="keyword">const</span> &amp;parameters, DefinitionT <span class="keyword">const</span> &amp;definition,
- <span class="keyword">bool</span> is_predefined);
-
- <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> undefined_macro(TokenT<span class="keyword">const</span> &amp;name);
- };
-
-}}} <span class="comment">// namespace boost::wave::context_policies</span></pre>
-<h2><a name="member_functions"></a>Member functions</h2>
-<h3>General hook functions </h3>
-<p><a name="found_directive"></a><strong>found_directive</strong></p>
-<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> found_directive(TokenT <span class="keyword">const </span>&amp;directive);
-</pre>
-<blockquote>
- <p>The function <tt>found_directive</tt> is called, whenever the preprocessor has detected one of the preprocessing directives (<span class="preprocessor">#define</span>, <span class="preprocessor">#undef</span>, <span class="preprocessor">#if</span>, <span class="preprocessor">#idef</span>, <span class="preprocessor">#ifndef</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#endif</span>, <span class="preprocessor">#error</span>, <span class="preprocessor">#include</span>, <span class="preprocessor">#pragma</span> or <span class="preprocessor">#warning</span>) .</p>
- <p>The parameter <tt>directive</tt> refers to the token containing the detected preprocessing directive. </p>
-</blockquote>
-<p><a name="may_skip_whitespace" id="may_skip"></a><strong>may_skipwhitespace</strong></p>
-<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">bool</span> may_skip_whitespace(ContextT <span class="keyword">const</span>&amp; ctx, TokenT &amp;token, <span class="keyword">bool</span>&amp; skipped_newline);
-</pre>
-<blockquote>
- <p>The function <tt>may_skipwhitespace</tt> will be called by the library, whenever a token is about to be returned to the calling application. </p>
- <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Wave V1.2.4 release. </p>
- <p>The <tt>token</tt> parameter holds a reference to the current token. The policy is free to change this token if needed.</p>
- <p>The <tt>skipped_newline</tt> parameter holds a reference to a boolean value which should be set to true by the policy function whenever a newline is going to be skipped. </p>
- <p>If the return value is <tt>true</tt>, the given token is skipped and the preprocessing continues to the next token. If the return value is <tt>false</tt>, the given token is returned to the calling application. Caution has to be used, because by returning <span class="keyword">true</span> the policy function is able to force skipping even significant tokens not only whitespace. </p>
-</blockquote>
-<h3>Conditional compilation hook functions </h3>
-<p><a name="evaluated_conditional_expression"></a><strong>evaluated_conditional_expression</strong></p>
-<pre><span class="keyword"> template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;<br><span class="keyword"> void</span> evaluated_conditional_expression(
- ContainerT <span class="keyword">const</span>&amp; expression, <span class="keyword">bool</span> expression_value);
-</pre>
-<blockquote>
- <p>The function <tt>evaluated_conditional_expression</tt> is called, whenever the preprocessor has encountered a <span class="preprocessor">#if</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#ifdef</span> or <span class="preprocessor">#ifndef</span> directive. This hook gets passed the non-expanded conditional expression (as it was given in the analysed source file) and the result of the evaluation of this expression in the current preprocessing context.</p>
- <p>The parameter <tt>expression</tt> holds the non-expanded token sequence
- comprising the evaluated expression.</p>
- <p>The parameter <tt>expression_value</tt> contains the result of the evaluation of
- the expression in the current preprocessing context.<br>
- </p>
-</blockquote>
-<p><a name="skipped_token"></a><strong>skipped_token</strong></p>
-<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> skipped_token(TokenT <span class="keyword">const</span>&amp; token);
-</pre>
-<blockquote>
- <p>The function <tt>skipped_token</tt> is called, whenever a token is about to be skipped due to a false preprocessor condition (code fragments to be
- skipped inside the not evaluated conditional <span class="preprocessor">#if</span>/<span class="preprocessor">#else</span>/<span class="preprocessor">#endif</span> branches).</p>
- <p>The parameter <tt>token</tt> refers to the token to be skipped.</p>
-</blockquote>
-<h3>Macro expansion tracking functions</h3>
-<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 is 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 is 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>
-<h3>Include file tracing functions</h3>
-<p><a name="opened_include_file" id="found_include_directive"></a><strong>found_include_directive</strong></p>
-<pre> <span class="keyword">void</span> found_include_directive(std::string <span class="keyword">const</span> &amp;filename,
- <span class="keyword">bool</span> include_next);
-</pre>
-<blockquote>
- <p>The function <tt>found_include_directive</tt> is called whenever whenever a #include directive was located..</p>
- <p>The parameter <tt>filename</tt> contains the (expanded) file name found after
- the <span class="preprocessor">#include</span> directive. This has the format <tt>&lt;file&gt;</tt>, <tt>&quot;file&quot;</tt> or
- <tt>file</tt>.
- The formats <tt>&lt;file&gt;</tt> or <tt>&quot;file&quot;</tt> are used for <span class="preprocessor">#include</span> directives found
- in the preprocessed token stream, the format <tt>file</tt> is used for files
- specified through the --force_include command line argument.</p>
- <p>The parameter <tt>include_next</tt> is set to true if the found directive was
- a <span class="preprocessor">#include_next</span> directive and the <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt> preprocessing constant was defined to something != 0.<br>
- </p>
-</blockquote>
-<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;rel_filename,
- std::string <span class="keyword">const</span> &amp;abs_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 <span class="preprocessor">#include</span> directive was successfully located and opened.</p>
- <p>The parameter <tt>rel_filename</tt> contains the (normalised) probably relative file system path of the opened file. The concrete format of this file name depends on the format of the include search path given to the library beforehand.</p>
- <p>The parameter <tt>abs_filename</tt> contains the (normalised) 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>
-<h3>Interpretation of #pragma's</h3>
-<p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p>
-<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;
- bool interpret_pragma(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option,
- ContainerT <span class="keyword">const</span> &amp;values,
- <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &amp;pragma_token);
-</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>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </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>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>
-<h3>Macro definition </h3>
-<p><strong><a name="defined_macro" id="defined_macro"></a>defined_macro</strong></p>
-<pre> <span class="keyword">template</span> &lt;
- <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT
- &gt;
- <span class="keyword">void</span> defined_macro(TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">bool</span> is_functionlike,
- ParametersT <span class="keyword">const</span> &amp;parameters, DefinitionT <span class="keyword">const</span> &amp;definition,
- <span class="keyword">bool</span> is_predefined);
-</pre>
-<blockquote> <p>The function <tt>defined_macro</tt> is called whenever a macro was defined successfully.</p>
- <p>The parameter <tt>name</tt> is a reference to the token holding the macro name.</p>
- <p>The parameter <tt>is_functionlike</tt> is set to true whenever the newly
- defined macro is defined as a function like macro.</p>
- <p>The parameter <tt>parameters</tt> holds the parameter tokens for the macro
- definition. If the macro has no parameters or if it is a object like
- macro, then this container is empty.</p>
- <p>The parameter <tt>definition</tt> contains the token sequence given as the
- replacement sequence (definition part) of the newly defined macro.</p>
- <p>The parameter <tt>is_predefined</tt> is set to true for all macros predefined
- during the initialisation pahase of the library.<br>
- </p>
-</blockquote>
-<p><strong><a name="undefined_macro" id="undefined_macro"></a>undefined_macro</strong></p>
-<pre> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
- <span class="keyword">void</span> undefined_macro(TokenT<span class="keyword">const</span> &amp;name);
-</pre>
-<blockquote>
- <p>The function <tt>undefined_macro</tt> is called whenever a macro definition
- was removed successfully.</p>
- <p>The parameter <tt>name</tt> holds the token of the macro which definition was removed.<br>
- </p>
-</blockquote>
-<table border="0">
- <tr>
- <td width="10"></td>
- <td width="30"></td>
- <td width="30"></td>
- <td width="30"></td>
- </tr>
-</table>
-<hr size="1">
-<p class="copyright">Copyright &copy; 2003-2008 Hartmut Kaiser<br>
- <br>
-<font size="2">Distributed under 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>
-<p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Tuesday, May 23, 2006 12:52<!-- #EndDate -->
-</span></p>
-</body>
-</html>

Modified: branches/release/libs/wave/doc/class_reference_context.html
==============================================================================
--- branches/release/libs/wave/doc/class_reference_context.html (original)
+++ branches/release/libs/wave/doc/class_reference_context.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -1,861 +1,484 @@
 <!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">
-
+<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 style="color: rgb(0, 0, 0); background-image: url(theme/bkd.gif);">
-
+<body style="color: rgb(0, 0, 0); background-image: url(theme/bkd.gif);">
 <table background="theme/bkd2.gif" border="0" cellspacing="2" width="100%">
-
   <tbody>
-
     <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="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"></td>
-
     </tr>
-
   </tbody>
 </table>
-
 <br>
-
 <table border="0">
-
   <tbody>
-
     <tr>
-
       <td width="10"></td>
-
       <td width="30"></td>
-
       <td width="30"></td>
-
       <td width="30"></td>
-
     </tr>
-
   </tbody>
 </table>
-
 <blockquote>
   <p>Introduction<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>
-
+ <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>boost::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
-dereferenced return the preprocessed tokens. Additionally it is used to
-control other aspects of the preprocessing, such as </p>
-
+<p>The <tt>boost::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
+ dereferenced return the preprocessed tokens. Additionally it is used to
+ control other aspects of the preprocessing, such as </p>
 <blockquote>
   <p><strong><img id="IMG1" src="theme/bullet.gif" height="13" width="13"></strong>&nbsp;include
-search paths, 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" height="13" width="13">&nbsp;</strong>which macros to
-predefine and which of the predefined macros to undefine<br>
-
- <strong><img src="theme/bullet.gif" height="13" width="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
-wave/cpp_context.hpp
-synopsis</b></h2>
-
+ search paths, 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" height="13" width="13">&nbsp;</strong>which macros to
+ predefine and which of the predefined macros to undefine<br>
+ <strong><img src="theme/bullet.gif" height="13" width="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 wave/cpp_context.hpp synopsis</b></h2>
 <pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {<br><span class="keyword">namespace</span> <span class="identifier">wave</span> { <br> <br> <span class="keyword"> struct</span> this_type {};<br><br> <span class="keyword">template</span> &lt;<br> <span class="keyword">typename</span> Iterator, <span class="keyword">typename</span> LexIterator, <br> <span class="keyword">typename</span> InputPolicy, <span class="keyword">typename</span> ContextPolicy,<br> <span class="keyword">typename</span> Derived = this_type<br> &gt; <br> <span class="keyword"> class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy <br> {<br> <span class="keyword">typedef</span> &lt;unspecified&gt; token_sequence_type;<br><br> <span class="keyword">public</span>: <br><br> <span class="keyword"> typedef</span> pp_iterator&lt;context&gt; iterator_type; <br> <span class="keyword">typedef</span> Token token_
type;<br> <span class="keyword">typedef</span> <span class="keyword">typename</span> token_type::position_type position_type;<br> <span class="keyword">typedef</span> std::list&lt;token_type&gt; token_sequence_type;<br><br><span class="comment"> // constructor</span><br> context(Iterator<span class="keyword"> const</span> &amp;first_, <br> Iterator <span class="keyword">const</span> &amp;last_, <br> <span class="keyword">char const</span> *fname = <span class="string">"&lt;Unknown&gt;"</span>,<br> ContextPolicy <span class="keyword">const</span>&amp; ctx_policy = ContextPolicy())<br><br> <span class="comment">// iterator interface</span><br> iterator_type begin() <span class="keyword">const</span>;<br> iterator_type begin(Iterator<span class="keywo
rd"> const</span> &amp;first, <br> Iterator <span class="keyword">const</span> &amp;last) <span class="keyword">const</span>;<br> iterator_type end() <span class="keyword">const</span>;<br><br> <span class="comment">// maintain include paths</span><br><span class="keyword"> bool</span> add_include_path(<span class="keyword">char const</span> *path_);<br> <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path_);<br> <span class="keyword">void</span> set_sysinclude_delimiter();<br> <br> size_t get_iteration_depth() <span class="keyword">const</span>;<br><br> <span class="comment"> // maintain defined m
acros</span><br> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword"> bool</span> add_macro_definition(<span class="keyword">String</span> macrostring, <br> <span class="keyword"> bool</span> is_predefined = <span class="keyword">false</span>);<br> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword"></span> <span class="keyword">bool</span> add_macro_definition(StringT <span class="keyword">const</span> &amp;name, <br> position_type <span class="keyword">const</span>&amp; pos, <span class="keyword">bool</span> has_params, <br> std::vector&lt;token_type&gt; &amp;parameters, <br> token_sequence_type &amp;definition, <br> <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>)<br><br> <span class="keyword"
>template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword">bool</span> is_defined_macro(<span class="keyword">String const</span> &amp;name) <span class="keyword">const</span>;<br> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword">bool</span> remove_macro_definition(String<span class="keyword"> const</span> &amp;name, <br> <span class="keyword"> bool</span> even_predefined = <span class="keyword">false</span>);<br> <span class="keyword">void</span> reset_macro_definitions();<br> <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword"> bool</span> <a href="class_reference_context.html#get_macro_definition">
get_macro_definition</a>(<br> <span class="keyword"> </span>String<span class="keyword"> const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword"><br> bool</span> &amp;is_predefined, position_type &amp;pos, <br> std::vector&lt;token_type&gt; &amp;parameters, <br> token_sequence_type &amp;definition) <span class="keyword">const</span>; <br><br> <span class="keyword">typedef</span> &lt;unspecified&gt; macromap_type;<br> <span class="keyword">typedef</span> typename macromap_type::name_iterator name_iterator;<br> <span class="keyword">typedef</span> typename macromap_type::const_name_iterator const_name_iterator;<br><br> name_iterator macro_names_begin();<br> name_iterator macro_names_end();<br> const_name_iterator <a href="class_reference_context.html#m
acro_names_iterators">macro_names_begin</a>() <span class="keyword">const</span>;<br> const_name_iterator macro_names_end() <span class="keyword">const</span>;<br><br> <span class="comment">// other options</span><br><span class="keyword"> void</span> set_language(language_support enable);<br> language_support get_language() <span class="keyword">const</span>;<br><br><span class="keyword"> void</span> set_max_include_nesting_depth(std::size_t new_depth);<br> size_t get_max_include_nesting_depth() <span class="keyword">const</span>;<br><br><span class="comment"> // get the Wave version information </span><br><span class="keyword"> static
 std::string</span> get_version();<br> <span class="keyword">static std::string</span> get_version_string();<br> };<br><br>} <span class="comment">// namespace wave</span><br>} <span class="comment">// namespace boost</span></pre>
-
 <h2><b><a name="template_parameters"></a>Template
-parameters</b></h2>
-
+ 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>
-
+ three template parameters to specify the concrete behaviour of its
+ operation. The following table describes these with more detail.</p>
 <table align="center" border="0" width="90%">
-
   <tbody>
-
     <tr>
-
       <td colspan="2" class="table_title"><b>Template
-parameters required for the <tt>boost::wave::context</tt>
-class </b></td>
-
+ parameters required for the <tt>boost::wave::context</tt> class </b></td>
     </tr>
-
     <tr>
-
       <td class="table_cells" width="32%"><code>Iterator</code></td>
-
- <td class="table_cells" width="68%">
- <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>
-
+ <td class="table_cells" width="68%"><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>LexIterator</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>
-
+ <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>InputPolicy</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>
-
+ <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>ContextPolicy</code></td>
-
- <td class="table_cells">
- <p>The type of the context policy class, which allows to
-customize different aspects of the behaviour of the preprocessing. The
-requirements of this policy and the available customization points
-provided by this policy are described here.&nbsp;&nbsp;
-&nbsp;</p>
-
- </td>
-
+ <td class="table_cells"><p>The type of the context policy class, which allows to
+ customize different aspects of the behaviour of the preprocessing. The
+ requirements of this policy and the available customization points
+ provided by this policy are described here.&nbsp;&nbsp;
+ &nbsp;</p></td>
     </tr>
-
     <tr class="table_cells">
-
       <td class="table_cells"><code>Derived</code></td>
-
- <td>
- <p>The type of the type being derived from the context type (if
-any). This template parameter is optional and defaults to 'this_type',
-which means that the context&nbsp;type will be used assuming no derived type exists. <br>
-
- </p>
- </td>
-
+ <td><p>The type of the type being derived from the context type (if
+ any). This template parameter is optional and defaults to 'this_type',
+ which means that the context&nbsp;type will be used assuming no derived type exists. <br>
+ </p></td>
     </tr>
-
   </tbody>
 </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>
-
+ refer to the <a href="class_reference_lexer.html">The
+ Lexer Interface </a>.</p>
 <p>If the template parameter <tt>InputPolicy</tt> is
-omitted, the template <tt>boost::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_inptpolcy.html">The
-Input Policy</a>.</p>
-
-<p>If the template parameter ContextPolicy is omitted, the <tt>boost::wave::context_policies::eat_whitespace</tt>
-policy type is used, implementing certain basic preprocessing hooks
-needed for normal (default) execution. For further information about
-the context policy, please refer to the topic The Context Policy.
-</p>
-
+ omitted, the template <tt>boost::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_inptpolcy.html">The
+ Input Policy</a>.</p>
+<p>If the template parameter ContextPolicy is omitted, the <tt>boost::wave::context_policies::eat_whitespace</tt> policy type is used, implementing certain basic preprocessing hooks
+ needed for normal (default) execution. For further information about
+ the context policy, please refer to the topic The Context Policy. </p>
 <h2><a name="public_typedefs"></a>Public
-Typedefs</h2>
-
+ Typedefs</h2>
 <p>The <tt>boost::wave::context</tt> template
-defines the following public typedefs, which may be useful while using
-this class:</p>
-
+ defines the following public typedefs, which may be useful while using
+ this class:</p>
 <table align="center" border="0" width="90%">
-
   <tbody>
-
     <tr>
-
       <td colspan="2" class="table_title"><b>Public
-typedef's defined by the <tt>boost::wave::context</tt>
-class </b></td>
-
+ typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
     </tr>
-
     <tr>
-
       <td class="table_cells"><code>iterator_type</code></td>
-
- <td class="table_cells">
- <p>The <tt>Iterator</tt> template parameter
-provided, while the <tt>context</tt> class was
-instantiated. </p>
-
- </td>
-
+ <td class="table_cells"><p>The <tt>Iterator</tt> template parameter
+ provided, while the <tt>context</tt> class was
+ instantiated. </p></td>
     </tr>
-
     <tr>
-
       <td class="table_cells"><code>lex_type</code></td>
-
- <td class="table_cells">
- <p>The <tt>LexIterator</tt> template parameter
-provided, while the <tt>context</tt> class was
-instantiated. </p>
-
- </td>
-
+ <td class="table_cells"><p>The <tt>LexIterator</tt> template parameter
+ provided, while the <tt>context</tt> class was
+ instantiated. </p></td>
     </tr>
-
     <tr>
-
       <td class="table_cells" width="32%"><code>token_type</code></td>
-
- <td class="table_cells" width="68%">
- <p>The token type, which is returned by the <tt>context</tt>
-generated iterators. This type is taken from the <tt>LexIterator</tt>
-template parameter provided, whicle the <tt>context</tt>
-class was instantiated.</p>
-
- </td>
-
+ <td class="table_cells" width="68%"><p>The token type, which is returned by the <tt>context</tt> generated iterators. This type is taken from the <tt>LexIterator</tt> template parameter provided, whicle the <tt>context</tt> class was instantiated.</p></td>
     </tr>
-
     <tr>
-
       <td class="table_cells"><code>input_policy_type</code></td>
-
- <td class="table_cells">
- <p>The <tt>InputPolicy</tt> template parameter
-provided, while the <tt>context</tt> class was
-instantiated. </p>
-
- </td>
-
+ <td class="table_cells"><p>The <tt>InputPolicy</tt> template parameter
+ provided, while the <tt>context</tt> class was
+ instantiated. </p></td>
     </tr>
-
     <tr>
-
       <td class="table_cells"><code>context_policy_type</code></td>
-
- <td class="table_cells">
- <p>The <tt>ContextPolicy</tt> template
-parameter provided, while the <tt>context</tt> class was
-instantiated. </p>
-
- </td>
-
+ <td class="table_cells"><p>The <tt>ContextPolicy</tt> template
+ parameter provided, while the <tt>context</tt> class was
+ instantiated. </p></td>
     </tr>
-
     <tr>
-
       <td class="table_cells"><code>position_type</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>
-
+ <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>
-
   </tbody>
 </table>
-
 <h2><b><a name="member_functions"></a>Member
-functions</b></h2>
-
+ functions</b></h2>
 <p><b><a name="constructor" id="constructor"></a>Constructor</b></p>
-
 <pre> context(Iterator <span class="keyword">const</span> &amp;first, <br> Iterator <span class="keyword">const</span> &amp;last, <span class="keyword">char</span> <span class="keyword">const</span> *filename, <br> ContextPolicy <span class="keyword">const</span>&amp; ctx_policy);</pre>
-
 <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">"&lt;Unknown&gt;"</span>. If
-the ctx_policy parameter isn't supplied it defaults to a default
-constructed <tt>ContextPolicy</tt> object. </p>
-
+ 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">"&lt;Unknown&gt;"</span>. If
+ the ctx_policy parameter isn't supplied it defaults to a default
+ constructed <tt>ContextPolicy</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;"..."</tt>
-directives).</p>
-
+ 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;"..."</tt> directives).</p>
 <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>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_type begin();<br> iterator_type begin(Iterator <span class="keyword">const</span> &amp;first,<br> Iterator <span class="keyword">const</span> &amp;last, <span class="keyword"></span>);</pre>
-
 <blockquote>
   <p>Initializes and returns the starting iterator for the
-preprocessed token stream. The iterator pair given by the parameters&nbsp; <tt>[first,&nbsp;last)</tt>
-specifies the input sequence to preprocess. The first version of this
-function uses the iinput stream as specified by the constructor.&nbsp;</p>
-
+ preprocessed token stream. The iterator pair given by the parameters&nbsp; <tt>[first,&nbsp;last)</tt> specifies the input sequence to preprocess. The first version of this
+ function uses the iinput stream as specified by the constructor.&nbsp;</p>
 </blockquote>
-
 <p><b><a name="iterator_interface_end" id="iterator_interface_end"></a></b><b>end</b></p>
-
 <pre> iterator_type 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>
-
+ 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 paths for include files. A search path for user include files
-and a search path for system include files. Any directories specified
-with the add_include_path()
-function before the function set_sysinclude_delimiter()
-is called are searched only for the case of <tt>#include&nbsp;"..."</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 add_include_path()
-function after a call to the function set_sysinclude_delimiter(),
-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 set_sysinclude_delimiter()
-inhibits the use of the current reference directory as the first search
-directory for <tt>#include&nbsp;"..."</tt> directives.
-Therefore, the current reference directory is searched only, if it is
-requested explicitly with a call to the function add_include_path("."). </p>
-
-<p>Callig both functions, the set_sysinclude_delimiter()
-and add_include_path(".")
-allows you to control precisely, which directories are searched before
-the current one and which are searched after.</p>
-
+ search paths for include files. A search path for user include files
+ and a search path for system include files. Any directories specified
+ with the add_include_path() function before the function set_sysinclude_delimiter() is called are searched only for the case of <tt>#include&nbsp;"..."</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 add_include_path() function after a call to the function set_sysinclude_delimiter(),
+ 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 set_sysinclude_delimiter() inhibits the use of the current reference directory as the first search
+ directory for <tt>#include&nbsp;"..."</tt> directives.
+ Therefore, the current reference directory is searched only, if it is
+ requested explicitly with a call to the function add_include_path("."). </p>
+<p>Callig both functions, the set_sysinclude_delimiter() and add_include_path(".") 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>
-
+ 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);<br></pre>
-
+<pre> <span class="keyword"> bool</span> add_include_path(<span class="keyword">char const</span> *path);<br>
+</pre>
 <blockquote>
   <p>Adds the given file system path to the user include search
-paths. After a call to the set_sysinclude_delimiter()
-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>
-
+ paths. After a call to the set_sysinclude_delimiter() 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>
-
+ 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 add_include_path(). Note
-though, that the given path is validated against the file system.</p>
-
+ paths. This function operates on the system include search path
+ regardless of the mode of operation of the add_include_path(). 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>
-
+ 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"></a><b>set_sysinclude_delimiter</b></p>
-
 <pre> <span class="keyword"> void</span> set_sysinclude_delimiter();</pre>
-
 <blockquote>
- <p>Switches the mode, how the add_include_path()
-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 add_include_path()
-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;"..."</tt>
-directives.</p>
-
+ <p>Switches the mode, how the add_include_path() 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 add_include_path() 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;"..."</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>
-
+ 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(<br> <span class="keyword"> std::string</span> macrostring, <span class="keyword">bool</span> is_predefined); <br></pre>
-
+<pre><span class="keyword"> bool</span> add_macro_definition(<br> <span class="keyword"> std::string</span> macrostring, <span class="keyword">bool</span> is_predefined); <br>
+</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>
-
+ 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 align="center" border="0" width="90%">
-
     <tbody>
-
       <tr>
-
         <td colspan="2" class="table_title"><b>Summary
-of possible formats for defining macros </b></td>
-
+ of possible formats for defining macros </b></td>
       </tr>
-
       <tr>
-
         <td class="table_cells" width="32%"><code>MACRO</code></td>
-
- <td class="table_cells" width="68%"><code>define
- <tt>MACRO</tt> as 1</code></td>
-
+ <td class="table_cells" width="68%"><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>
-
+ <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>
-
+ <td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td>
       </tr>
-
       <tr>
-
         <td class="table_cells" width="32%"><code>MACRO(x)</code></td>
-
- <td class="table_cells" width="68%"><code>define
- <tt>MACRO(x)</tt> as 1</code></td>
-
+ <td class="table_cells" width="68%"><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>
-
+ <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>
-
+ <td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td>
       </tr>
-
     </tbody>
   </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>
-
+ 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>
-
+ 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"> template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword">bool</span> is_defined_macro(String <span class="keyword">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>
-
+ <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><strong><a name="get_macro_definition"></a>get_macro_definition</strong></p>
-
 <pre> <span class="keyword"> template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword">bool</span> get_macro_definition(<br> <span class="keyword"> </span>String<span class="keyword"> const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword"><br> bool</span> &amp;is_predefined, position_type &amp;pos, <br> std::vector&lt;token_type&gt; &amp;parameters, <br> token_sequence_type &amp;definition) <span class="keyword">const</span>; </pre>
-
 <blockquote>
   <p>Allows to retrieve all information known with regard to a
-macro definition. The parameter <tt>name</tt> specifies
-the name of the macro the information should be returned for. The
-parameters <tt>is_function_style</tt> and <tt>is_predefined</tt>
-return, whether the macro has been defined as a function style macro or
-as a predefined macro resp. The parameter <tt>pos</tt>
-will contain the position the macro was defined at. The parameter <tt>parameters</tt>
-will contain the names of the parameters the macro was defined with and
-the parameter <tt>definition</tt> will contain the token
-sequence for the definition (macro body).</p>
-
+ macro definition. The parameter <tt>name</tt> specifies
+ the name of the macro the information should be returned for. The
+ parameters <tt>is_function_style</tt> and <tt>is_predefined</tt> return, whether the macro has been defined as a function style macro or
+ as a predefined macro resp. The parameter <tt>pos</tt> will contain the position the macro was defined at. The parameter <tt>parameters</tt> will contain the names of the parameters the macro was defined with and
+ the parameter <tt>definition</tt> will contain the token
+ sequence for the definition (macro body).</p>
   <p>The function returns <tt>true</tt> is the macro
-was defined and the requested information has been successfully
-retrieved, <tt>false</tt> otherwise.</p>
-
+ was defined and the requested information has been successfully
+ retrieved, <tt>false</tt> otherwise.</p>
 </blockquote>
-
 <p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p>
-
 <pre><span class="keyword"> </span> <span class="keyword"> template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword"> bool</span> remove_macro_definition(<br> String<span class="keyword"> 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>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>
-
+ 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>
-
+ 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 here.</p>
-
+ undefines all user defined macros and inserts the internal predefined
+ macros as described here.</p>
 </blockquote>
-
 <p><a name="macro_names_iterators"></a><b>macro_names_begin,
-macro_names_end </b></p>
-
-<pre> name_iterator macro_names_begin();<br> name_iterator macro_names_end();<br> const_name_iterator macro_names_begin() <span class="keyword">const</span>;<br> const_name_iterator macro_names_end() <span class="keyword">const</span>;<br></pre>
-
-<blockquote>
- <p>The <tt>macro_names_begin</tt> and <tt>macro_names_end</tt>
-functions return iterators allowing to iterate on the names of all
-defined macros.</p>
-
+ macro_names_end </b></p>
+<pre> name_iterator macro_names_begin();<br> name_iterator macro_names_end();<br> const_name_iterator macro_names_begin() <span class="keyword">const</span>;<br> const_name_iterator macro_names_end() <span class="keyword">const</span>;<br>
+</pre>
+<blockquote>
+ <p>The <tt>macro_names_begin</tt> and <tt>macro_names_end</tt> functions return iterators allowing to iterate on the names of all
+ defined macros.</p>
 </blockquote>
-
 <h3><a name="get_version"></a>Get Version
-information</h3>
-
+ 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>
-
+ 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">"v.rr.ss.bbbb"</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">"0.9.1.454"</span>. The returned value
-is the same as it will be inserted in the preprocessed token stream,
-when the predefined macro <tt>__WAVE_VERSION_STR__</tt> is
-expanded.</p>
-
+ formatted as <span class="string">"v.rr.ss.bbbb"</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">"0.9.1.454"</span>. The returned value
+ is the same as it will be 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="language_support"></a>set_language<br>
-
-get_language</p>
-
+ get_language</p>
 <pre><span class="keyword"> void</span> set_language(<span class="keyword">language_support</span> language, <br> <span class="keyword">bool</span> reset_macros = <span class="keyword">true</span>);<br> <span class="keyword">language_support</span> get_language() <span class="keyword">const</span>;</pre>
-
 <blockquote>
   <p>This functions allows 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>language_support</tt>:</p>
-
+ the <tt>Wave</tt> library should work. The possible
+ language modes are defined by the enumerated type <tt>language_support</tt>:</p>
   <pre> <span class="keyword">enum</span> language_support {<br> <span class="comment">// support flags for C++98</span><br> support_normal = 0x01,<br> support_cpp = support_normal,<br><span class="comment"><br> // support flags for C99</span><br> support_option_long_long = 0x02,<br> support_option_variadics = 0x04,<br> support_c99 = support_option_variadics | support_option_long_long | 0x08,<br><span class="comment"><br> // the mask for the main language settings</span><br> support_option_mask = 0xFF80,<br><br><span class="comment"> // additional fine tuning of the general behavior</span><br> support_option_insert_whitespace = 0x0080,<br> support_option_preserve_comments = 0x0100,<br> support_option_no_character_validation = 0x0200,<br> support_option_convert_trigraphs = 0x0400,<br> support_option_single_line = 0x0800,<br> support_option_prefer_pp_numbers = 0x1000,<br> support_option_emit_line_directiv
es = 0x2000,<br> support_option_include_guard_detection = 0x4000,<br> support_option_emit_pragma_directives = 0x8000<br> };</pre>
-
- <p>When used with <tt>support_option_variadics</tt>
-the support for variadics, placemarkers and the <tt>operator&nbsp;_Pragma()</tt>
-is enabled in normal C++ mode. When used with the <tt>support_option_long_long</tt>
-the support for long long suffixes is enabled in C++ mode. </p>
-
+ <p>When used with <tt>support_option_variadics</tt> the support for variadics, placemarkers and the <tt>operator&nbsp;_Pragma()</tt> is enabled in normal C++ mode. When used with the <tt>support_option_long_long</tt> the support for long long suffixes is enabled in C++ mode. </p>
   <p>The <tt>support_c99</tt> switches on the C99
-language support, which enables variadics, placemarkers, the <tt>operator&nbsp;_Pragma</tt>
-and long long suffixes by default. Additionally it disables the C++
-specific tokens such as <tt>'-&gt;*'</tt>, <tt>'.*'</tt>,
- <tt>'::'</tt> etc. </p>
-
+ language support, which enables variadics, placemarkers, the <tt>operator&nbsp;_Pragma</tt> and long long suffixes by default. Additionally it disables the C++
+ specific tokens such as <tt>'-&gt;*'</tt>, <tt>'.*'</tt>, <tt>'::'</tt> etc. </p>
   <p>The <tt>support_option_...</tt> values are to
-be used in conjunction with the main language settings (<tt>support_normal</tt>
-and <tt>support_c99</tt>) . </p>
-
+ be used in conjunction with the main language settings (<tt>support_normal</tt> and <tt>support_c99</tt>) . </p>
   <ul>
-
- <li>If the <tt>support_option_insert_whitespace</tt>
-flag is set,&nbsp;the <tt>Wave</tt> library &nbsp;inserts
-additional whitespace between tokens where the concatenated string
-representation of the two tokens would form another valid C++ token.
-This is very importatnt to avoid mis-interpretations of the generated
-output if it is going to be processed by a C++ compiler afterwards.
-&nbsp; </li>
- <li>If the <tt>support_option_preserve_comments</tt>
-flag is set, the <tt>Wave</tt> library preserves almost
-all comments in the source code. The only comments not preserved are
-those contained inside macro definitions. If this flag is not set all
-comments are replaced by a single space. </li>
-
- <li>If the <tt>support_option_no_character_validation</tt>
-flag is set , the <tt>Wave</tt> library does not validate
-universal character literals (given in the form of <tt>'u1234'</tt>
-or <tt>'U12345678'</tt>) to be in the allowed value range.
-This flag is merely used for internal purposes by the testing framework
-and will be rarely used by a user of the library.</li>
-
- <li>If the <tt>support_option_convert_trigraphs</tt>
-flag is set, the <tt>Wave</tt> library replaces all
-occurences of trigraph characters with their non-trigraph character
-sequence (i.e. <tt>'??='</tt> is replaced by <tt>'#'</tt>
-etc.) . By default no replacement is performed. </li>
-
- <li>If the <tt>support_option_single_line</tt>
-flag is set, the <tt>Wave</tt> library will now reprot an
-error if the last line of the processed input is not terminated by a
-new line. This flag is merely used for internal purposes by the testing
-framework and will be rarely used by a user of the library.</li>
-
- <li>If the <tt>support_option_prefer_pp_numbers</tt>
-flag is set, the <tt>Wave</tt> library is instructed to
-correctly identify pp-number's in the input stream. These get
-recognized into 'normal' number tokens before they get returned to the
-calling application. The flag is set by default and is used merely for
-internal purposes and will be rarely reset by a user of the library. </li>
-
- <li>If the <span class="keyword">support_option_emit_line_directives</span>
-flag is set, the <tt>Wave</tt> library will emit <span class="preprocessor">#line</span> directives in the
-generated token stream, if appropriate. This flag is set by default, to
-prevent the library from generating <span class="preprocessor">#line</span>
-directives it must be reset explicitely. </li>
-
- <li>If the <span class="keyword">support_option_include_guard_detection</span>
-flag is set, the <tt>Wave</tt> library will try to
-automatically identify include guards during the processing of a
-included file. Files which contained include guards are handled as if
-they contained a #pragma once, i.e. these files wonn#t be opened twice,
-even if specified in a second <span class="preprocessor">#include</span>
-statement. </li>
-
+ <li>If the <tt>support_option_insert_whitespace</tt> flag is set,&nbsp;the <tt>Wave</tt> library &nbsp;inserts
+ additional whitespace between tokens where the concatenated string
+ representation of the two tokens would form another valid C++ token.
+ This is very importatnt to avoid mis-interpretations of the generated
+ output if it is going to be processed by a C++ compiler afterwards.
+ &nbsp; </li>
+ <li>If the <tt>support_option_preserve_comments</tt> flag is set, the <tt>Wave</tt> library preserves almost
+ all comments in the source code. The only comments not preserved are
+ those contained inside macro definitions. If this flag is not set all
+ comments are replaced by a single space. </li>
+ <li>If the <tt>support_option_no_character_validation</tt> flag is set , the <tt>Wave</tt> library does not validate
+ universal character literals (given in the form of <tt>'u1234'</tt> or <tt>'U12345678'</tt>) to be in the allowed value range.
+ This flag is merely used for internal purposes by the testing framework
+ and will be rarely used by a user of the library.</li>
+ <li>If the <tt>support_option_convert_trigraphs</tt> flag is set, the <tt>Wave</tt> library replaces all
+ occurences of trigraph characters with their non-trigraph character
+ sequence (i.e. <tt>'??='</tt> is replaced by <tt>'#'</tt> etc.) . By default no replacement is performed. </li>
+ <li>If the <tt>support_option_single_line</tt> flag is set, the <tt>Wave</tt> library will now reprot an
+ error if the last line of the processed input is not terminated by a
+ new line. This flag is merely used for internal purposes by the testing
+ framework and will be rarely used by a user of the library.</li>
+ <li>If the <tt>support_option_prefer_pp_numbers</tt> flag is set, the <tt>Wave</tt> library is instructed to
+ correctly identify pp-number's in the input stream. These get
+ recognized into 'normal' number tokens before they get returned to the
+ calling application. The flag is set by default and is used merely for
+ internal purposes and will be rarely reset by a user of the library. </li>
+ <li>If the <span class="keyword">support_option_emit_line_directives</span> flag is set, the <tt>Wave</tt> library will emit <span class="preprocessor">#line</span> directives in the
+ generated token stream, if appropriate. This flag is set by default, to
+ prevent the library from generating <span class="preprocessor">#line</span> directives it must be reset explicitely. </li>
+ <li>If the <span class="keyword">support_option_include_guard_detection</span> flag is set, the <tt>Wave</tt> library will try to
+ automatically identify include guards during the processing of a
+ included file. Files which contained include guards are handled as if
+ they contained a #pragma once, i.e. these files wonn#t be opened twice,
+ even if specified in a second <span class="preprocessor">#include</span> statement. </li>
   </ul>
-
   <blockquote>
     <p>During this process the library will recognize two forms
-of include guards:</p>
-
+ of include guards:</p>
     <pre> <span class="preprocessor">#ifndef</span> INCLUDE_GUARD_MACRO<br> <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO<br> ...<br> <span class="preprocessor">#endif</span><br>or<br><span class="preprocessor"> #if</span> !defined(INCLUDE_GUARD_MACRO)<br> <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO<br> ...<br> <span class="preprocessor">#endif</span></pre>
-
     <p> Note, that the parenthesis in the second form are
-optional (i.e. <tt>!defined INCLUDE_GUARD_MACRO</tt> will
-work as well). The code allows for any whitespace, newline and single
-'#' tokens before the <span class="preprocessor">#if</span>/<span class="preprocessor">#ifndef</span> and after the
-final <span class="preprocessor">#endif</span> for
-the include guard to be recognized.</p>
-
+ optional (i.e. <tt>!defined INCLUDE_GUARD_MACRO</tt> will
+ work as well). The code allows for any whitespace, newline and single
+ '#' tokens before the <span class="preprocessor">#if</span>/<span class="preprocessor">#ifndef</span> and after the
+ final <span class="preprocessor">#endif</span> for
+ the include guard to be recognized.</p>
     <p>This flag is on by default, so if you do not want the
-library to automatically reconize include guards you will need to reset
-this explicitely. </p>
-
+ library to automatically reconize include guards you will need to reset
+ this explicitely. </p>
   </blockquote>
-
   <ul>
-
- <li>If the <tt>support_option_emit_pragma_directives</tt>
-flag is set, the <tt>Wave</tt> library will emit all
-unknown <span class="preprocessor">#pragma</span>
-directives to the output. This suport option will be recognized only if
-the <tt>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</tt> is defined
-during compilation to a value not equal to zero (see here for more
-information). </li>
-
+ <li>If the <tt>support_option_emit_pragma_directives</tt> flag is set, the <tt>Wave</tt> library will emit all
+ unknown <span class="preprocessor">#pragma</span> directives to the output. This suport option will be recognized only if
+ the <tt>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</tt> is defined
+ during compilation to a value not equal to zero (see here for more
+ information). </li>
   </ul>
-
- <p><strong> </strong>If the parameter <tt>reset_macros</tt>
-is true the <tt>set_language</tt> function internally
-resets the list of defined macros, so please be careful not to call it
-after you have defined your own macros already. </p>
-
+ <p><strong> </strong>If the parameter <tt>reset_macros</tt> is true the <tt>set_language</tt> function internally
+ resets the list of defined macros, so please be careful not to call it
+ after you have defined your own macros already. </p>
 </blockquote>
-
 <p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br>
-
-get_max_include_nesting_depth</p>
-
+ get_max_include_nesting_depth</p>
 <pre><span class="keyword"> void</span> set_max_include_nesting_depth(size_t new_depth); <br> 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 here).</p>
-
+ 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 here).</p>
 </blockquote>
-
 <table border="0">
-
   <tbody>
-
     <tr>
-
       <td width="10"></td>
-
       <td width="30"></td>
-
       <td width="30"></td>
-
       <td width="30"></td>
-
     </tr>
-
   </tbody>
 </table>
-
 <hr size="1">
 <p class="copyright">Copyright &copy; 2003-2008
-Hartmut Kaiser<br>
-
-<br>
-
-<font size="2">Distributed under 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>
-
+ Hartmut Kaiser<br>
+ <br>
+ <font size="2">Distributed under 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"></span>
 <p class="copyright"><span class="updated">Last
-updated:<!-- #BeginDate format:fcAm1m --> Sunday, December
-2, 2007 19:12<!-- #EndDate --> </span>
-</p>
-
+ updated:
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:30<!-- #EndDate -->
+ </span> </p>
 <p>&nbsp;</p>
-
 </body>
 </html>

Modified: branches/release/libs/wave/doc/class_reference_ctxpolicy.html
==============================================================================
--- branches/release/libs/wave/doc/class_reference_ctxpolicy.html (original)
+++ branches/release/libs/wave/doc/class_reference_ctxpolicy.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -22,7 +22,7 @@
       </td>
 
     <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The
- Context Policy (new, current interface) </font></b></font></td>
+ Context Policy </font></b></font></td>
 
     <td width="96"></td>
 
@@ -677,7 +677,7 @@
 http://www.boost.org/LICENSE_1_0.txt) </font> </p>
 
 <p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Sunday, December 2, 2007 19:12<!-- #EndDate -->
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:31<!-- #EndDate -->
 </span></p>
 
 </body>

Modified: branches/release/libs/wave/doc/compiletime_config.html
==============================================================================
--- branches/release/libs/wave/doc/compiletime_config.html (original)
+++ branches/release/libs/wave/doc/compiletime_config.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -149,7 +149,7 @@
 </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_type</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> [3] based lexer used by default. It is implemented based on the <tt>SLex</tt> [5] lexer example written by Dan Nuffer. The token type used therein is functionally equivalent to the default token type except for an additional <tt>operator&lt;&lt;</tt> used for dumping the information carried by the token.</P>
+<P dir="ltr">The <tt>Wave</tt> library contains several samples illustrating these possibilities. 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> [3] based lexer used by default. It is implemented based on the <tt>SLex</tt> [5] lexer example written by Dan Nuffer. The token type used therein is functionally equivalent to the default token type except for an additional <tt>operator&lt;&lt;</tt> used for dumping the information carried by 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
@@ -219,8 +219,8 @@
     <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::cpp_grammar_gen&lt;<tt>LexIteratorT</tt>&gt;;<br>
+ <span class="keyword"> 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>
@@ -244,7 +244,7 @@
 <font size="2">Distributed under 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"></span>
 <p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Wednesday, January 31, 2008 16:50<!-- #EndDate -->
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:38<!-- #EndDate -->
 </span></p>
 </body>
 </html>

Modified: branches/release/libs/wave/doc/quickstart.html
==============================================================================
--- branches/release/libs/wave/doc/quickstart.html (original)
+++ branches/release/libs/wave/doc/quickstart.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -71,13 +71,13 @@
         <span class="identifier">context_type</span><span class="special">;</span>
 
     context_type ctx(input.begin(), input.end(), <span class="string">&quot;input.cpp&quot;</span>);
-
-<span class="comment"> // At this point you may want to set the parameters of the
+<span class="comment">
+ // At this point you may want to set the parameters of the
     // preprocessing as include paths and/or predefined macros.
 </span> ctx.add_include_path(<span class="literal">&quot;...&quot;</span>);
         ctx.add_macro_definition(...);
-
-<span class="comment"> // Get the preprocessor iterators and use them to generate
+<span class="comment">
+ // Get the preprocessor iterators and use them to generate
     // the token sequence.
 </span> context_type::iterator_type first = ctx.begin();
     context_type::iterator_type last = ctx.end();
@@ -115,7 +115,7 @@
 <font size="2">Distributed under 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"></span>
 <p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Sunday, December 2, 2007 19:06<!-- #EndDate -->
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:34<!-- #EndDate -->
 </span></p>
 </body>
 </html>

Modified: branches/release/libs/wave/doc/wave_driver.html
==============================================================================
--- branches/release/libs/wave/doc/wave_driver.html (original)
+++ branches/release/libs/wave/doc/wave_driver.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -248,14 +248,14 @@
   <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
+ <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 at startup looks for a configuration
   file named 'wave.cfg' in every directory up the file system hierarchy starting
   from the directory where the input file is located. The first file found stops
- the search. If a file exists, it is treated as a normal
+ the search. If a 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>
@@ -273,7 +273,7 @@
 <font size="2">Distributed under 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"></span>
 <p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Tuesday, June 26, 2007 20:19<!-- #EndDate -->
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:40<!-- #EndDate -->
 </span></p>
 </body>
 </html>

Modified: branches/release/libs/wave/index.html
==============================================================================
--- branches/release/libs/wave/index.html (original)
+++ branches/release/libs/wave/index.html 2008-07-29 21:42:38 EDT (Tue, 29 Jul 2008)
@@ -5,105 +5,102 @@
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <link href="doc/theme/style.css" rel="stylesheet" type="text/css">
 </head>
-<body text="#000000" background="doc/theme/bkd.gif">
-<table width="100%" border="0" cellspacing="2" background="doc/theme/bkd2.gif">
- <tr>
- <td width="21"> <h1></h1></td>
- <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">Wave V2.0</font></b></font></td>
- <td width="96"></td>
- </tr>
+<body style="color: rgb(0, 0, 0); background-image: url(doc/theme/bkd.gif);">
+<table background="doc/theme/bkd2.gif" border="0" cellspacing="2" width="100%">
+ <tbody>
+ <tr>
+ <td width="21">&nbsp;</td>
+ <td width="885"><font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Wave V2.0</b></font></td>
+ <td width="96"></td>
+ </tr>
+ </tbody>
 </table>
 <br>
-<table width="75%" border="0" align="center">
- <tr>
- <td class="table_title">Table of Contents</td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Preface</td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Introduction</td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Quick Start</td>
- </tr>
- <tr>
- <td class="toc_cells_L0"><b><font face="Geneva, Arial, Helvetica, san-serif">Class
- References </font></b></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_context.html">The Context
- Object</a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_inptpolcy.html">The Input
- Policy </a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_ctxpolicy.html">The Context
- Policy (new, current interface) </a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1" style="height: 27px"><a href="doc/class_ref_ctxpolicy_depr.html">The Context
- Policy (depreciated interface) </a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_lexer.html">The Lexer Iterator Interface
- </a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_tokentype.html">The Token
- Type</a></td>
- </tr>
- <tr>
- <td class="toc_cells_L1">The Token Identifiers </td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/class_reference_filepos.html">The File
- Position</a></td>
- </tr>
- <tr>
- <td class="toc_cells_L0"><b>Predefined Macros</b></td>
- </tr>
- <tr>
- <td class="toc_cells_L0"><a href="doc/macro_expansion_process.html">The Macro
- Expansion Process</a></td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Compile Time Configuration</td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Samples</td>
- </tr>
- <tr>
- <td class="toc_cells_L0"><b>The Wave Driver Executable</b></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><b><a href="doc/wave_driver.html">The Wave Driver Command
- Line </a></b></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><b>The Tracing Facility</b></td>
- </tr>
- <tr>
- <td class="toc_cells_L1"><a href="doc/supported_pragmas.html">Supported Pragma
- Directives </a></td>
- </tr>
- <tr>
- <td class="toc_cells_L0">Acknowledgments</td>
- </tr>
- <tr>
- <td class="toc_cells_L0">References </td>
- </tr>
+<table align="center" border="0" width="75%">
+ <tbody>
+ <tr>
+ <td class="table_title">Table of Contents</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Preface</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Introduction</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Quick Start</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0"><b><font face="Geneva, Arial, Helvetica, san-serif">Class References </font></b></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The Context Object</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The Input Policy </td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The Context Policy</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1"><a href="doc/class_reference_lexer.html">The Lexer Iterator
+ Interface </a></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The Token Type</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The Token Identifiers </td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1">The File Position</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0"><b>Predefined Macros</b></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0"><a href="doc/macro_expansion_process.html">The Macro Expansion
+ Process</a></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Compile Time Configuration</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Samples</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0"><b>The Wave Driver
+ Executable</b></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1"><b>The Wave Driver Command Line </b></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1"><b>The Tracing Facility</b></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L1"><a href="doc/supported_pragmas.html">Supported Pragma
+ Directives </a></td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">Acknowledgments</td>
+ </tr>
+ <tr>
+ <td class="toc_cells_L0">References </td>
+ </tr>
+ </tbody>
 </table>
 <br>
 <hr size="1">
-<p class="copyright">Copyright &copy; 2003-2008 Hartmut Kaiser<br>
+<p class="copyright">Copyright &copy; 2003-2008
+ Hartmut Kaiser<br>
   <br>
-<font size="2">Distributed under 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>
+ <font size="2">Distributed under 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"></span>
-<p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Sunday, December 2, 2007 18:57<!-- #EndDate -->
-</span></p>
+<p class="copyright"><span class="updated">Last updated:
+ <!-- #BeginDate format:fcAm1m -->Tuesday, July 29, 2008 20:31<!-- #EndDate -->
+ </span></p>
 </body>
 </html>


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk