|
Boost-Commit : |
From: hartmut.kaiser_at_[hidden]
Date: 2008-07-29 17:37:10
Author: hkaiser
Date: 2008-07-29 17:37:09 EDT (Tue, 29 Jul 2008)
New Revision: 47871
URL: http://svn.boost.org/trac/boost/changeset/47871
Log:
Wave: More documentation changes
Text files modified:
branches/release/libs/wave/doc/class_reference_context.html | 1234 +++++++++++++++++++++++++--------------
branches/release/libs/wave/doc/class_reference_ctxpolicy.html | 657 ++++++++++++++------
branches/release/libs/wave/doc/preface.html | 130 +++
3 files changed, 1342 insertions(+), 679 deletions(-)
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 17:37:09 EDT (Tue, 29 Jul 2008)
@@ -1,515 +1,861 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <title>The Context Object</title>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <link rel="stylesheet" href="theme/style.css" type="text/css">
- </head>
- <body text="#000000" background="theme/bkd.gif">
-<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
- <tr>
- <td width="21"> <h1></h1></td>
- <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The
- Context Object</font></b></font></td>
- <td width="96"></td>
- </tr>
+<head>
+ <title>The Context Object</title>
+
+
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
+ <link rel="stylesheet" href="theme/style.css" type="text/css">
+
+</head>
+
+
+ <body 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="96"></td>
+
+ </tr>
+
+ </tbody>
</table>
+
<br>
- <table border="0">
- <tr>
+
+<table border="0">
+
+ <tbody>
+
+ <tr>
+
<td width="10"></td>
+
<td width="30"></td>
- <td width="30"></td>
+
+ <td width="30"></td>
+
<td width="30"></td>
+
</tr>
- </table>
-<blockquote>
+
+ </tbody>
+</table>
+
+<blockquote>
<p>Introduction<br>
- Header 'wave/context.hpp' synopsis<br>
- Public Typedefs<br>
- Template parameters<br>
- Member functions</p>
- </blockquote>
+
+ <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<></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" height="13" src="theme/bullet.gif" width="13"></STRONG> include
- search paths, which define, where to search for files to be included with
- <tt>#include <...></tt> and <tt>#include "..."</tt> directives<br>
- <STRONG><img src="theme/bullet.gif" width="13" height="13"> </STRONG>which
- macros to predefine and which of the predefined macros to undefine<br>
- <STRONG><img src="theme/bullet.gif" width="13" height="13"> </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> {
-<span class="keyword">namespace</span> <span class="identifier">wave</span> {
-
- <span class="keyword">template</span> <
- <span class="keyword">typename</span> Iterator, <span class="keyword">typename</span> LexIterator,
- <span class="keyword">typename</span> InputPolicy, <span class="keyword">typename</span> ContextPolicy
- >
- <span class="keyword">class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy
- {
- <span class="keyword">public</span>:
-
- <span class="keyword">typedef</span> pp_iterator<context> iterator_type;
- <span class="keyword">typedef</span> Token token_type;
- <span class="keyword">typedef</span> <span class="keyword">typename</span> token_type::position_type position_type;
- <span class="keyword">typedef</span> std::list<token_type> token_sequence_type;<br>
- <span class="comment">// constructor</span>
- context(Iterator<span class="keyword"> const</span> &first_,
- Iterator <span class="keyword">const</span> &last_,
- <span class="keyword">char const</span> *fname = <span class="string">"<Unknown>"</span>,
- ContextPolicy <span class="keyword">const</span>& ctx_policy = ContextPolicy())
-
- <span class="comment">// iterator interface</span>
- iterator_type begin() <span class="keyword">const</span>;
- iterator_type end() <span class="keyword">const</span>;
-
- <span class="comment">// maintain include paths</span>
- <span class="keyword">bool</span> add_include_path(<span class="keyword">char const</span> *path_);
- <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path_);
- <span class="keyword">void</span> set_sysinclude_delimiter();
-
- size_t get_iteration_depth() <span class="keyword">const</span>;
-
- <span class="comment">// maintain defined macros</span>
- <span class="keyword">bool</span> add_macro_definition(<span class="keyword">std::string</span> macrostring,
- <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>);
- <span class="keyword">template</span> <<span class="keyword">typename</span> String>
- <span class="keyword">bool</span> is_defined_macro(<span class="keyword">String const</span> &name) <span class="keyword">const</span>;
- <span class="keyword">bool</span> remove_macro_definition(<span class="keyword">std::string const</span> &name,
- <span class="keyword">bool</span> even_predefined = <span class="keyword">false</span>);
- <span class="keyword">void</span> reset_macro_definitions();
- <span class="keyword"> bool</span></span> get_macro_definition(
- <span class="keyword"> std::string const</span> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword">
- bool</span> &is_predefined, position_type &pos,
- std::vector<token_type> &parameters,
- token_sequence_type &definition) <span class="keyword">const</span>;
- name_iterator macro_names_begin();
- name_iterator macro_names_end();
- const_name_iterator macro_names_begin() <span class="keyword">const</span>;
- const_name_iterator macro_names_end() <span class="keyword">const</span>;
-
- <span class="comment">// other options</span>
- <span class="keyword">void</span> set_language(language_support enable);
- language_support get_language() <span class="keyword">const</span>;<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>
- <span class="comment">// get the Wave version information </span>
- <span class="keyword">static std::string</span> get_version();
- <span class="keyword">static std::string</span> get_version_string();
- };
-
-} <span class="comment">// namespace wave</span>
-} <span class="comment">// namespace boost</span></pre>
-<h2><b><a name="template_parameters"></a>Template parameters</b></h2>
-<p>The <tt>boost::wave::context</tt> object has three template parameters to specify
- the concrete behaviour of its operation. The following table describes these
- with more detail.</p>
-<table width="90%" border="0" align="center">
- <tr>
- <td colspan="2" class="table_title"><b>Template parameters required for the
- <tt>boost::wave::context</tt> class </b></td>
- </tr>
- <tr>
- <td width="32%" class="table_cells"><code>Iterator</code></td>
- <td width="68%" class="table_cells"><p>The type of the underlying iterator,
- through which the input stream is accessed. <br>
- This should be at least an <tt>forward_iterator</tt> type iterator.</p></td>
- </tr>
- <tr>
- <td class="table_cells"><code>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>
- </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>
- </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.</p></td>
- </tr>
+
+<p>The <tt>boost::wave::context<></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> include
+search paths, which define, where to search for files to be included
+with <tt>#include <...></tt> and <tt>#include "..."</tt>
+directives<br>
+
+ <strong><img src="theme/bullet.gif" height="13" width="13"> </strong>which macros to
+predefine and which of the predefined macros to undefine<br>
+
+ <strong><img src="theme/bullet.gif" height="13" width="13"> </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> <<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> > <br> <span class="keyword"> class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy <br> {<br> <span class="keyword">typedef</span> <unspecified> token_sequence_type;<br><br> <span class="keyword">public</span>: <br><br> <span class="keyword"> typedef</span> pp_iterator<context> 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<token_type> token_sequence_type;<br><br><span class="comment"> // constructor</span><br> context(Iterator<span class="keyword"> const</span> &first_, <br> Iterator <span class="keyword">const</span> &last_, <br> <span class="keyword">char const</span> *fname = <span class="string">"<Unknown>"</span>,<br> ContextPolicy <span class="keyword">const</span>& 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> &first, <br> Iterator <span class="keyword">const</span> &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> <<span class="keyword">typename</span> String><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> <<span class="keyword">typename</span> String><br><span class="keyword"></span> <span class="keyword">bool</span> add_macro_definition(StringT <span class="keyword">const</span> &name, <br> position_type <span class="keyword">const</span>& pos, <span class="keyword">bool</span> has_params, <br> std::vector<token_type> &parameters, <br> token_sequence_type &definition, <br> <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>)<br><br> <span class="keyword"
>template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> is_defined_macro(<span class="keyword">String const</span> &name) <span class="keyword">const</span>;<br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> remove_macro_definition(String<span class="keyword"> const</span> &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> <<span class="keyword">typename</span> String><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> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword"><br> bool</span> &is_predefined, position_type &pos, <br> std::vector<token_type> &parameters, <br> token_sequence_type &definition) <span class="keyword">const</span>; <br><br> <span class="keyword">typedef</span> <unspecified> 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>
+
+<p>The <tt>boost::wave::context</tt> object has
+three template parameters to specify the concrete behaviour of its
+operation. The following table describes these with more detail.</p>
+
+<table 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>
+
+ </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>
+
+ </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>
+
+ </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>
+
+ </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.
+ </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 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>
-<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 The Input Policy.</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 <a href="class_reference_ctxpolicy.html">The
- Context Policy</a>. </p>
-<h2><a name="public_typedefs"></a>Public Typedefs</h2>
-<p>The <tt>boost::wave::context</tt> template defines the following public typedefs, which may be useful while using this class:</p>
-<table width="90%" border="0" align="center">
- <tr>
- <td colspan="2" class="table_title"><b>Public typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
- </tr>
- <tr>
- <td class="table_cells"><code>iterator_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>
- </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>
- </tr>
- <tr>
- <td width="32%" class="table_cells"><code>token_type</code></td>
- <td width="68%" class="table_cells"><p>The token type, which is returned by the <tt>context</tt> generated iterators. This type is taken from the <tt>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>
- </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>
- </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>
- </tr>
+
+<p>For further information about the lexer type to use, please
+refer to the <a href="class_reference_lexer.html">The
+Lexer Interface </a>.</p>
+
+<p>If the template parameter <tt>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>
+
+<h2><a name="public_typedefs"></a>Public
+Typedefs</h2>
+
+<p>The <tt>boost::wave::context</tt> template
+defines the following public typedefs, which may be useful while using
+this class:</p>
+
+<table 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>
+
+ </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>
+
+ </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>
+
+ </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>
+
+ </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>
+
+ </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>
+
+ </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>
+
+ </tr>
+
+ </tbody>
</table>
-<h2><b><a name="member_functions"></a>Member functions</b></h2>
+
+<h2><b><a name="member_functions"></a>Member
+functions</b></h2>
+
<p><b><a name="constructor" id="constructor"></a>Constructor</b></p>
-<pre> context(Iterator <span class="keyword">const</span> &first,
- Iterator <span class="keyword">const</span> &last, <span class="keyword">char</span> <span class="keyword">const</span> *filename,
- ContextPolicy <span class="keyword">const</span>& ctx_policy);</pre>
- <p>Constructs a context object on top of the input stream given by the pair
- of auxilliary iterators <tt>[first, 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">"<Unknown>"</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 "..."</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, 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>
+
+<pre> context(Iterator <span class="keyword">const</span> &first, <br> Iterator <span class="keyword">const</span> &last, <span class="keyword">char</span> <span class="keyword">const</span> *filename, <br> ContextPolicy <span class="keyword">const</span>& ctx_policy);</pre>
+
+<p>Constructs a context object on top of the input stream given
+by the pair of auxilliary iterators <tt>[first, 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">"<Unknown>"</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 "..."</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, 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();</pre>
+
+<pre> iterator_type begin();<br> iterator_type begin(Iterator <span class="keyword">const</span> &first,<br> Iterator <span class="keyword">const</span> &last, <span class="keyword"></span>);</pre>
+
<blockquote>
- <p>Initializes and returns the starting iterator for the preprocessed token
- stream.</p>
-
+ <p>Initializes and returns the starting iterator for the
+preprocessed token stream. The iterator pair given by the parameters <tt>[first, last)</tt>
+specifies the input sequence to preprocess. The first version of this
+function uses the iinput stream as specified by the constructor. </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>
+
+<blockquote>
+ <p>Initializes and returns the end of stream iterator to
+compare with for detecting the end of the preprocessed token stream.</p>
+
</blockquote>
+
<h3>Maintain include paths</h3>
-<p>The <tt>Wave</tt> library maintains two separate search 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 "..."</tt>
- directives, they are not searched for <tt>#include <file></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 "..."</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>
+
+<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 "..."</tt>
+directives, they are not searched for <tt>#include <file></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 "..."</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>
+
</p>
+
<p><a name="add_include_path"></a><b>add_include_path</b></p>
-<pre> <span class="keyword">bool</span> add_include_path(<span class="keyword">char const</span> *path);
-</pre>
-<blockquote>
- <p>Adds the given file system path to the user include search paths. After a
- call to the 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>
+
+<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>
+
+ <p>If the given path string does not form a name of a valid
+file system directory item, the function returns <tt>false</tt>.
+If the given path was successfully added to the include search paths in
+question, the function returns <tt>true</tt>.</p>
+
</blockquote>
+
<p><a name="add_sysinclude_path"></a><b>add_sysinclude_path</b></p>
+
<pre> <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path);</pre>
-<blockquote>
- <p>Adds the given file system path to the system include search paths. This
- function operates on the system include search path regardless of the mode
- of operation of the 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>
+
+<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>
+
+ <p>If the given path string does not form a name of a valid
+file system directory item, the function returns <tt>false</tt>.
+If the given path was successfully added to the system include search
+paths, the function returns <tt>true</tt>.</p>
+
</blockquote>
+
<p><a name="set_sysinclude_delimiter"></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 "..."</tt>
- directives.</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 "..."</tt>
+directives.</p>
+
</blockquote>
+
<p><a name="get_iteration_depth"></a><b>get_iteration_depth</b></p>
+
<pre> size_t get_iteration_depth() <span class="keyword">const</span>;</pre>
-<blockquote>
- <p>Returns the actual include iteration depth, i.e. the current number of include
- levels to be poped from the include iteration context, before the main (topmost)
- iteration context is reached.</p>
+
+<blockquote>
+ <p>Returns the actual include iteration depth, i.e. the current
+number of include levels to be poped from the include iteration
+context, before the main (topmost) iteration context is reached.</p>
+
</blockquote>
+
<h3>Maintain defined macros</h3>
+
<p><a name="add_macro_definition"></a><b>add_macro_definition</b></p>
-<pre><span class="keyword"> bool</span> add_macro_definition(
- <span class="keyword">std::string</span> macrostring,
- bool is_predefined);
-</pre>
-<blockquote>
- <p>Adds a new macro definition to the macro symbol table. The parameter <tt>macrostring</tt>
- should contain the macro to define in the command line format, i.e. something
- like <tt>MACRO(x)=definition</tt>. The following table describes this format
- in more detail. The parameter <tt>is_predefined</tt> should be true while
- defining predefined macros, i.e. macros, which are not undefinable with an
- <tt>#undef</tt> directive from inside the preprocessed input stream. If this
- parameter is not given, it defaults to <tt>false</tt>.</p>
- <table width="90%" border="0" align="center">
- <tr>
- <td colspan="2" class="table_title"><b>Summary of possible formats for defining
- macros </b></td>
- </tr>
- <tr>
- <td width="32%" class="table_cells"><code>MACRO</code></td>
- <td width="68%" class="table_cells"><code>define <tt>MACRO</tt> as 1</code></td>
- </tr>
- <tr>
- <td class="table_cells"><code>MACRO=</code></td>
- <td class="table_cells"><code>define <tt>MACRO</tt> as nothing (empty)</code></td>
- </tr>
- <tr>
- <td class="table_cells"><code>MACRO=definition</code></td>
- <td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td>
- </tr>
- <tr>
- <td width="32%" class="table_cells"><code>MACRO(x)</code></td>
- <td width="68%" class="table_cells"><code>define <tt>MACRO(x)</tt> as 1</code></td>
- </tr>
- <tr>
- <td class="table_cells"><code>MACRO(x)=</code></td>
- <td class="table_cells"><code>define <tt>MACRO(x)</tt> as nothing (empty)</code></td>
- </tr>
- <tr>
- <td class="table_cells"><code>MACRO(x)=definition</code></td>
- <td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td>
- </tr>
+
+<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>
+
+ <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>
+
+ </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>
+
+ </tr>
+
+ <tr>
+
+ <td class="table_cells"><code>MACRO=</code></td>
+
+ <td class="table_cells"><code>define <tt>MACRO</tt>
+as nothing (empty)</code></td>
+
+ </tr>
+
+ <tr>
+
+ <td class="table_cells"><code>MACRO=definition</code></td>
+
+ <td class="table_cells"><code>define <tt>MACRO</tt>
+as <tt>definition</tt></code></td>
+
+ </tr>
+
+ <tr>
+
+ <td 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>
+
+ </tr>
+
+ <tr>
+
+ <td class="table_cells"><code>MACRO(x)=</code></td>
+
+ <td class="table_cells"><code>define <tt>MACRO(x)</tt>
+as nothing (empty)</code></td>
+
+ </tr>
+
+ <tr>
+
+ <td class="table_cells"><code>MACRO(x)=definition</code></td>
+
+ <td class="table_cells"><code>define <tt>MACRO(x)</tt>
+as <tt>definition</tt></code></td>
+
+ </tr>
+
+ </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>
- <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>
+
+ <p>The function returns <tt>false</tt>, if the
+macro to define already was defined and the new definition is
+equivalent to the existing one, it returns true, if the new macro was
+successfully added to the macro symbol table.</p>
+
+ <p>If the given macro definition resembles a redefinition and
+the new macro is not identical to the already defined macro (in the
+sense defined by the C++ Standard), the function throws a corresponding
+ <tt>preprocess_exception</tt>.</p>
+
</blockquote>
+
<p><a name="is_defined_macro"></a><b>is_defined_macro</b></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> String>
- <span class="keyword">bool</span></span> is_defined_macro(String <span class="keyword">const</span> &name) <span class="keyword">const</span>; </pre>
+
+<pre> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> is_defined_macro(String <span class="keyword">const</span> &name) <span class="keyword">const</span>; </pre>
+
<blockquote>
- <p>Returns, if a macro with the given <tt>name</tt> is defined, i.e. if it is
- contained in the macro symbol table.</p>
- </blockquote>
+ <p>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">bool</span></span> get_macro_definition(
- <span class="keyword">std::string const</span> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword">
- bool</span> &is_predefined, position_type &pos,
- std::vector<token_type> &parameters,
- token_sequence_type &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>
- <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>
+
+<pre> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> get_macro_definition(<br> <span class="keyword"> </span>String<span class="keyword"> const</span> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword"><br> bool</span> &is_predefined, position_type &pos, <br> std::vector<token_type> &parameters, <br> token_sequence_type &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>
+
+ <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>
+
</blockquote>
+
<p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p>
-<pre><span class="keyword"> bool</span> remove_macro_definition(
- <span class="keyword">std::string const</span> &name,
- <span class="keyword">bool</span> even_predefined); </pre>
-<blockquote>
- <p>Removes the definition of the macro with the given <tt>name</tt> from the
- macro symbol table. This operation is equivalent to an <tt>#undef</tt> directive
- with this <tt>name</tt> executed from within the input stream. If the parameter
- <tt>even_predefined</tt> is <tt>true</tt>, then the macro is removed from
- the macro symbol table even, if it is defined as a predefined macro. </p>
- <p>Note though, that the following macros are <b>not</b> undefinable in any
- case: <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt>,
- <tt>__cplusplus</tt>, <tt>__STDC__</tt>. If the parameter <tt>even_predefined</tt>
- is not given, it defaults to <tt>false</tt>.</p>
- <p>The function returns <tt>false</tt>, if the macro to undefine was not defined
- and returns <tt>true</tt> otherwise.</p>
- <p>If the macro to remove may not be undefined (it is a predefined macro and
- the parameter <tt>even_predefined</tt> is set to <tt>false</tt> or it is one
- of the mentioned not undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p>
+
+<pre><span class="keyword"> </span> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br><span class="keyword"> bool</span> remove_macro_definition(<br> String<span class="keyword"> const</span> &name, <span class="keyword">bool</span> even_predefined); </pre>
+
+<blockquote>
+ <p>Removes the definition of the macro with the given <tt>name</tt>
+from the macro symbol table. This operation is equivalent to an <tt>#undef</tt>
+directive with this <tt>name</tt> executed from within the
+input stream. If the parameter <tt>even_predefined</tt> is
+ <tt>true</tt>, then the macro is removed from the macro
+symbol table even, if it is defined as a predefined macro. </p>
+
+ <p>Note though, that the following macros are <b>not</b>
+undefinable in any case: <tt>__FILE__</tt>, <tt>__LINE__</tt>,
+ <tt>__DATE__</tt>, <tt>__TIME__</tt>, <tt>__cplusplus</tt>,
+ <tt>__STDC__</tt>. If the parameter <tt>even_predefined</tt>
+is not given, it defaults to <tt>false</tt>.</p>
+
+ <p>The function returns <tt>false</tt>, if the
+macro to undefine was not defined and returns <tt>true</tt>
+otherwise.</p>
+
+ <p>If the macro to remove may not be undefined (it is a
+predefined macro and the parameter <tt>even_predefined</tt>
+is set to <tt>false</tt> or it is one of the mentioned not
+undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p>
+
</blockquote>
+
<p><a name="reset_macro_definitions"></a><b>reset_macro_definitions</b></p>
+
<pre><span class="keyword"> void</span> reset_macro_definitions(); </pre>
+
<blockquote>
- <p>Resets the macro symbol table to it's initial state, i.e. undefines all user defined macros and inserts the internal predefined macros as described here.</p>
+ <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>
+
</blockquote>
-<p><a name="macro_names_iterators"></a><b>macro_names_begin, macro_names_end </b></p>
-<pre> name_iterator macro_names_begin();
- name_iterator macro_names_end();
- const_name_iterator macro_names_begin() <span class="keyword">const</span>;
- const_name_iterator macro_names_end() <span class="keyword">const</span>;
-</pre>
+
+<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>
+ <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>
+
+<h3><a name="get_version"></a>Get Version
+information</h3>
+
<p><b>get_version</b></p>
-<pre><span class="keyword"> </span><span class="keyword">static std::string</span> get_version(); </pre>
+
+<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>
+ <p>Returns a string containing the current Wave version
+formatted as <span class="string">0xvvrsbbbb</span>
+(this is a string representation of the equivalent hexadecimal number),
+where <span class="literal">'vv'</span> is the
+version number, <span class="literal">'r'</span>
+the release number, <span class="literal">'s'</span>
+the subrelease number and <span class="literal">'bbbb'</span>
+the build number. A possible return value looks like <span class="literal">0x00910454</span>. The returned value
+is the same as is inserted in the preprocessed token stream, when the
+predefined macro <tt>__WAVE_VERSION__</tt> is expanded.</p>
+
</blockquote>
+
<p><b>get_version_str</b></p>
-<pre><span class="keyword"> </span><span class="keyword">static std::string</span> get_version_str(); </pre>
-<blockquote>
- <p>Returns a string containing the current Wave version formatted as <span class="string">"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>
+
+<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>
+
</blockquote>
+
<h3>Control extended options</h3>
+
<p><a name="language_support"></a>set_language<br>
- get_language</p>
-<pre><span class="keyword"> void</span> set_language(<span class="keyword">language_support</span> language,
- <span class="keyword">bool</span> reset_macros = <span class="keyword">true</span>);
- <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>
- <pre> <span class="keyword">enum</span> language_support {
- <span class="comment">// support flags for C++98</span>
- support_normal = 0x01,
- support_cpp = support_normal,
-
- <span class="comment">// support flags for C99</span>
- support_option_long_long = 0x02,
- support_option_variadics = 0x04,
- support_c99 = support_option_variadics |
- support_option_long_long |
- 0x08,
-
-<span class="comment"> // the mask for the main language settings</span>
- support_option_mask = 0xFF00,<br>
-<span class="comment"> // additional fine tuning of the general behavior</span>
- support_option_preserve_comments = 0x0100,
- support_option_no_character_validation = 0x0200,
- support_option_convert_trigraphs = 0x0400,
- support_option_single_line = 0x0800,
- support_option_prefer_pp_numbers = 0x1000,
- support_option_emit_line_directives = 0x2000,
- support_option_include_guard_detection = 0x4000,
- support_option_emit_pragma_directives = 0x8000
- };</pre>
- <p>When used with <tt>support_option_variadics</tt> the support for variadics, placemarkers
- and the <tt>operator _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 _Pragma</tt> and long long suffixes by default. Additionally it disables the C++ specific tokens such as <tt>'->*'</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>
+
+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>
+
+ <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 _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 _Pragma</tt>
+and long long suffixes by default. Additionally it disables the C++
+specific tokens such as <tt>'->*'</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>
+
<ul>
- <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, the <tt>Wave</tt> library 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.
+ </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>
- <pre> <span class="preprocessor">#ifndef</span> INCLUDE_GUARD_MACRO
- <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO
- ...
- <span class="preprocessor">#endif</span>
-
- or
-
- <span class="preprocessor">#if</span> !defined(INCLUDE_GUARD_MACRO)
- <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO
- ...
- <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>
- <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>
+ <p>During this process the library will recognize two forms
+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>
+
+ <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>
+
</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>
-<pre><span class="keyword"> void</span> set_max_include_nesting_depth(size_t new_depth);
- size_t get_max_include_nesting_depth() <span class="keyword">const</span>;</pre>
-<blockquote>
- <p>This functions allow to set or to get the maximal possible include file nesting
- depth supported by the <tt>Wave</tt> library. The initial value for this is
- determined by the preprocessing constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt>
- (see here).</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>
+
</blockquote>
+
<table border="0">
- <tr>
- <td width="10"></td>
- <td width="30"></td>
- <td width="30"></td>
- <td width="30"></td>
- </tr>
+
+ <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 © 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">Copyright © 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>
+
<span class="updated"></span>
-<p class="copyright"><span class="updated">Last updated:
- <!-- #BeginDate format:fcAm1m -->Sunday, December 2, 2007 19:12<!-- #EndDate -->
- </span>
+<p class="copyright"><span class="updated">Last
+updated:<!-- #BeginDate format:fcAm1m --> Sunday, December
+2, 2007 19:12<!-- #EndDate --> </span>
</p>
+
<p> </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 17:37:09 EDT (Tue, 29 Jul 2008)
@@ -1,441 +1,684 @@
<!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">
+
+
+ <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>
+
+<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 Policy (new, current interface) </font></b></font></td>
- <td width="96"></td>
+
+ <td width="96"></td>
+
</tr>
+
+ </tbody>
</table>
+
<br>
+
<table border="0">
- <tr>
+
+ <tbody>
+ <tr>
+
<td width="10"></td>
+
<td width="30"></td>
- <td width="30"></td>
+
+ <td width="30"></td>
+
<td width="30"></td>
+
</tr>
+
+ </tbody>
</table>
+
<blockquote>
+
<p>Introduction<br>
+
<a href="class_reference_ctxpolicy.html#header_synopsis">Header 'wave/preprocessing_hooks.hpp'
synopsis</a><br>
+
<a href="class_reference_ctxpolicy.html#member_functions">Member functions</a></p>
+
</blockquote>
+
<h2><b><a name="introduction"></a>Introduction</b></h2>
-<p>Please note that the following description relates to the new preprocessing hooks interface used by default starting with the Boost V1.35.0 release. If you are interested in the older interface please look here. </p>
+
+<p>Please note that the following description relates to the new
+preprocessing hooks interface used by default starting with the Boost
+V1.35.0 release. If you are interested in the older interface please
+look here. </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 closed, </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 recognized. </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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span> &ctx,
- TokenT <span class="keyword">const </span>&directive);<br>
- <span class="comment">// test, whether a given token may be skipped</span><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">bool</span> may_skip_whitespace (ContextT <span class="keyword">const</span>& ctx,
- TokenT &token, <span class="keyword">bool</span> &skipped_newline);<br>
- </span><span class="comment">// Conditional compilation</span><span class="keyword">
- template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> evaluated_conditional_expression(
- ContextT <span class="keyword">const</span> &ctx, ContainerT <span class="keyword">const</span>& expression, <br> <span class="keyword">bool</span> expression_value);<br>
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span> &ctx,
- TokenT <span class="keyword">const</span></span>& token);<br>
- <span class="comment">// macro expansion tracing</span><span class="keyword">
+<pre><span class="keyword">namespace</span> boost {<br><span class="keyword">namespace</span> wave {<br><span class="keyword">namespace</span> context_policies {<br> <br> <span class="keyword">struct</span> default_preprocessing_hooks {<br><br> <span class="comment">// general hook functions</span>
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const </span>&directive);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT><br> void throw_exception(ContextT <span class="keyword">const</span> &ctx, <br> ExceptionT <span class="keyword">const</span>& e);<br><br> <span class="comment">// test, whether a given token may be skipped</span><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> <a href="c
lass_reference_ctxpolicy.html#may_skip_whitespace">may_skip_whitespace</a> (ContextT <span class="keyword">const</span>& ctx,<br> TokenT &token, <span class="keyword">bool</span> &skipped_newline);<br>
+ <span class="comment">// Conditional compilation</span><span class="keyword">
+ template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <br> <span class="keyword">typename</span> ContainerT<br> ><br> <span class="keyword">bool</span> evaluated_conditional_expression(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span>& directive, <br> ContainerT <span class="keyword">const</span>& expression, <span class="keyword">bool</span> expression_value);<br>
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const</span>& token);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> TokenT <span class="keyword">const</span>& generated_token(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const</span>& token);<br><br> <span class="comment">// macro expansion tracing</span><span class="keyword">
template</span> <<span class="keyword">
- typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT,
- <span class="keyword">typename</span> IteratorT
- >
- <span class="keyword">bool</span> expanding_function_like_macro(
- ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macrodef,
- <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args,
- ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall,
- <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,
- IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> expanding_object_like_macro(
- ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macro,
- ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span> &ctx,
- ContainerT <span class="keyword">const</span> &result);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span> &ctx,
- ContainerT <span class="keyword">const</span> &result);
-
- <span class="comment">// include file tracing functions</span>
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span> &ctx,
- std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">void </span>opened_include_file(ContextT <span class="keyword">const</span> &ctx,
- std::string <span class="keyword">const</span> &relname, std::string const& absname,
- std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">void</span> returning_from_include_file(ContextT <span class="keyword">const</span> &ctx);
-
- <span class="comment">// interpretation of #pragma's of the form </span>
+ typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT,<br> <span class="keyword">typename</span> IteratorT<br> ><br> <span class="keyword">bool</span> expanding_function_like_macro(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macrodef, <br> <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall, <br> <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,<br> IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);<br> <br>
<span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> expanding_object_like_macro(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macro, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);<br> <br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &result);<br> <br>
<span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &result);<br><br> <span class="comment">// include file tracing functions</span>
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span> &ctx, <br> std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void </span>opened_include_file(ContextT <span class="keyword">const</span> &ctx, <br> std::string <span class="keyword">const</span> &relname, std::string const& absname,<br> <span class="keyword">bool</span> is_system_include); <br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="key
word">void</span> returning_from_include_file(ContextT <span class="keyword">const</span> &ctx);<br><br> <span class="comment">// interpretation of #pragma's of the form </span>
<span class="comment">// 'wave option[(value)]'</span>
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> interpret_pragma(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option,
- ContainerT <span class="keyword">const</span> &values,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &pragma_token);
-
- <span class="comment">// macro definition hooks</span>
- <span class="keyword">template</span> <
- <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">
- typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT
- >
- <span class="keyword">void</span> defined_macro(ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &name, <span class="keyword">
- bool</span> is_functionlike, ParametersT <span class="keyword">const</span> &parameters,
- DefinitionT <span class="keyword">const</span> &definition, <span class="keyword">bool</span> is_predefined);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">void</span> undefined_macro(ContextT <span class="keyword">const</span> &ctx,
- TokenT<span class="keyword"> const</span> &name);
-
- <span class="comment">// #error and #warning directive hooks</span>
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> found_warning_directive(ContextT <span class="keyword">const</span> &ctx,
- ContainerT <span class="keyword">const</span> &message);
-
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> found_error_directive(ContextT <span class="keyword">const</span> &ctx,
- ContainerT <span class="keyword">const</span> &message);
-
- <span class="comment">// #line directive hook</span>
- <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> found_line_directive(ContextT <span class="keyword">const</span> &ctx,
- ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,
- std::string <span class="keyword">const</span>& filename);
- };
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> interpret_pragma(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option, <br> ContainerT <span class="keyword">const</span> &values, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &pragma_token);<br><br> <span class="comment">// macro definition hooks</span>
+ <span class="keyword">template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">
+ typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT<br> ><br> <span class="keyword">void</span> defined_macro(ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &name, <span class="keyword">
+ bool</span> is_functionlike, ParametersT <span class="keyword">const</span> &parameters, <br> DefinitionT <span class="keyword">const</span> &definition, <span class="keyword">bool</span> is_predefined);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> undefined_macro(ContextT <span class="keyword">const</span> &ctx, <br> TokenT<span class="keyword"> const</span> &name);<br><br> <span class="comment">// #error and #warning directive hooks</span>
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> found_warning_directive(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &message);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> found_error_directive(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &message);<br><br> <span class="comment">// #line directive hook</span>
+ <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> found_line_directive(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,<br> std::string <span class="keyword">const</span>& filename);<br> };<br><br>}}} <span class="comment">// namespace boost::wave::context_policies</span></pre>
-}}} <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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const </span>&directive);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const </span>&directive);<br></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 <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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </p>
+
+
<p>The parameter <tt>directive</tt> refers to the token containing the detected preprocessing directive. </p>
- <p>If the return value is <tt>true</tt>, the directive will be skipped altogether, i.e. no preprocessing is done. The overall directive is replaced by a single newline character. If the return value is <tt>false</tt>, the directive is processed in the normal manner. </p>
+
+
+ <p>If the return value is <tt>true</tt>, the directive will be
+skipped altogether, i.e. no preprocessing is done. The overall
+directive is replaced by a single newline character. If the return
+value is <tt>false</tt>, the directive is processed in the normal manner. </p>
+
</blockquote>
+
+<p><a name="throw_exception"></a><strong>throw_exception</strong></p>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT><br> void throw_exception(ContextT <span class="keyword">const</span> &ctx, <br> ExceptionT <span class="keyword">const</span>& e);</pre>
+
+<blockquote>
+
+ <p>he function <tt>throw_exception</tt> is called, whenever a preprocessing exception occurs .</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 parameter <tt>e</tt> is the exception object containing detailed error information. </p>
+
+
+</blockquote>
+
<p><a name="may_skip_whitespace" id="may_skip"></a><strong>may_skipwhitespace</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">bool</span> may_skip_whitespace(ContextT <span class="keyword">const</span>& ctx, TokenT &token,
- <span class="keyword">bool</span>& skipped_newline);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> may_skip_whitespace(ContextT <span class="keyword">const</span>& ctx, TokenT &token, <br> <span class="keyword">bool</span>& skipped_newline);<br></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>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>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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br><span class="keyword"> bool</span> evaluated_conditional_expression(ContextT <span class="keyword">const</span>& ctx,
- ContainerT <span class="keyword">const</span>& expression, <span class="keyword">bool</span> expression_value);
-</pre>
+
+<pre><span class="keyword"> template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br><span class="keyword"> bool</span> evaluated_conditional_expression(ContextT <span class="keyword">const</span>& ctx, <br> TokenT <span class="keyword">const</span>& directive, ContainerT <span class="keyword">const</span>& expression, <span class="keyword"><br> bool</span> expression_value);<br></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 <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 Boost V1.35.0 release. </p>
+
+ <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 <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 Boost V1.35.0 release. </p>
+
+
+ <p>The <tt>token</tt> parameter holds a reference to the evaluated directive token. </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. </p>
- <p>The return value defines, whether the given expression has to be evaluated again, allowing to decide which of the conditional branches should be expanded. You need to return '<span class="keyword">true</span>' from this hook function to force the expression to be re-evaluated. Note, this was changed from a '<span class="keyword">void</span>' for the Boost V1.35.0 release. <br>
+
+
+ <p>The return value defines, whether the given expression has to be
+evaluated again, allowing to decide which of the conditional branches
+should be expanded. You need to return '<span class="keyword">true</span>' from this hook function to force the expression to be re-evaluated. Note, this was changed from a '<span class="keyword">void</span>' for the Boost V1.35.0 release. <br>
+
</p>
+
</blockquote>
+
<p><a name="skipped_token"></a><strong>skipped_token</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span>& token);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span>& token);<br></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 <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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </p>
+
+
<p>The parameter <tt>token</tt> refers to the token to be skipped.</p>
+
+</blockquote>
+
+<p><a name="generated_token"></a><strong>generated_token</strong></p>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> TokenT <span class="keyword">const</span>& generated_token(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span>& token);<br></pre>
+
+<blockquote>
+
+ <p>The function <tt>generated_token</tt> is called, whenever a token is about to be returned from the library.</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 Boost V1.35.0 release. </p>
+
+
+ <p>The parameter <tt>token</tt> refers to the token about to be
+returned from the library. This function may alter the token, but in
+this case it must be implemented with a non-const reference for the
+token parameter, allowing to modify the token in place.</p>
+ <p>The default behavior is to return the passed token reference unchanged to the caller.</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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> expanding_function_like_macro(
- ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macrodef,
- <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args,
- ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall,
- <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,
- IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);</pre>
+
+<pre><span class="keyword"> template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> expanding_function_like_macro(<br> ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macrodef, <br> <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall, <br> <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,<br> IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);</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>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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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>
+
+
<p>The parameters <tt>seqstart</tt> and <tt>seqend</tt> point into the input token
stream allowing to access the whole token sequence comprising the macro
invocation (starting with the opening parenthesis and ending after the
closing one).</p>
- <p>If the return value is <tt>true</tt>, the macro is not expanded, i.e. the overall macro invocation sequence, including the parameters are copied to the output without further processing . If the return value is <tt>false</tt>, the macro is expanded as expected. <br>
+
+
+ <p>If the return value is <tt>true</tt>, the macro is not expanded,
+i.e. the overall macro invocation sequence, including the parameters
+are copied to the output without further processing . If the return
+value is <tt>false</tt>, the macro is expanded as expected. <br>
+
</p>
+
</blockquote>
+
<p><a name="expanding_object_like_macro"></a><b>expanding_object_like_macro</b></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> expanding_object_like_macro(
- ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macro,
- ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> expanding_object_like_macro(<br> ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macro, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);<br></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>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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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>
+
+
<p>If the return value is <tt>true</tt>, the macro is not expanded, i.e. the macro symbol is copied to the output without further processing. If the return value is <tt>false</tt>, the macro is expanded as expected. <br>
-</p>
+
+ </p>
+
</blockquote>
+
<p><a name="expanded_macro"></a><b>expanded_macro</b></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result);<br></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 <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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result);<br></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 <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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span>& ctx,
- std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span>& ctx, <br> std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next);<br></pre>
+
<blockquote>
+
<p>The function <tt>found_include_directive</tt> is called whenever whenever a #include directive was located..</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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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><file></tt>, <tt>"file"</tt> or <tt>file</tt>.
- The formats <tt><file></tt> or <tt>"file"</tt> are used for <span class="preprocessor">#include</span> directives found
+ the <span class="preprocessor">#include</span> directive. This has the format <tt><file></tt>, <tt>"file"</tt> or <tt>file</tt>.
+ The formats <tt><file></tt> or <tt>"file"</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.</p>
- <p>If the return value is <tt>true</tt>, the include directive is not executed, i.e. the file to include is not loaded nor processed. The overall directive is replaced by a single newline character. If the return value is <tt>false</tt>, the directive is executed in a normal manner. <br>
+
+
+ <p>If the return value is <tt>true</tt>, the include directive is not
+executed, i.e. the file to include is not loaded nor processed. The
+overall directive is replaced by a single newline character. If the
+return value is <tt>false</tt>, the directive is executed in a normal manner. <br>
+
</p>
+
</blockquote>
+
<p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">void</span> opened_include_file(ContextT <span class="keyword">const</span>& ctx,
- std::string <span class="keyword">const</span> &rel_filename, std::string <span class="keyword">const</span> &abs_filename,
- std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> opened_include_file(ContextT <span class="keyword">const</span>& ctx, <br> std::string <span class="keyword">const</span> &rel_filename, std::string <span class="keyword">const</span> &abs_filename, <br> <span class="keyword">bool</span> is_system_include);<br></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 <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 Boost V1.35.0 release. </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 <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 Boost V1.35.0 release. </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 <...></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">template</span> <<span class="keyword">typename</span> ContextT>
- <span class="keyword">void</span> returning_from_include_file(ContextT <span class="keyword">const</span>& ctx);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> returning_from_include_file(ContextT <span class="keyword">const</span>& ctx);<br></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>
- <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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- bool interpret_pragma(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending,
- <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option,
- ContainerT <span class="keyword">const</span> &values,
- <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &pragma_token);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> bool interpret_pragma(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option, <br> ContainerT <span class="keyword">const</span> &values, <br> <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &pragma_token);<br></pre>
+
<blockquote>
+
<p>The function <tt>interpret_pragma</tt> is called whenever an unrecognized
- <tt>#pragma wave ...</tt> or operator <tt>_Pragma("wave ...")</tt>
+ <tt>#pragma wave ...</tt> or operator <tt>_Pragma("wave ...")</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 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> <
- <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">
- typename</span> DefinitionT
- >
- <span class="keyword">void</span> defined_macro(ContextT <span class="keyword">const</span>& ctx,
- TokenT <span class="keyword">const</span> &name, <span class="keyword">bool</span> is_functionlike,
- ParametersT <span class="keyword">const</span> &parameters, DefinitionT <span class="keyword">const</span> &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 <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 Boost V1.35.0 release. </p>
+
+<pre> <span class="keyword">template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">
+ typename</span> DefinitionT<br> ><br> <span class="keyword">void</span> defined_macro(ContextT <span class="keyword">const</span>& ctx, <br> TokenT <span class="keyword">const</span> &name, <span class="keyword">bool</span> is_functionlike,<br> ParametersT <span class="keyword">const</span> &parameters, DefinitionT <span class="keyword">const</span> &definition,<br> <span class="keyword">bool</span> is_predefined);<br></pre>
+
+<blockquote>
+ <p>The function <tt>defined_macro</tt> is called whenever a macro was defined successfully.</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 Boost V1.35.0 release. </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> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT>
- <span class="keyword">void</span> undefined_macro(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &name);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> undefined_macro(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &name);<br></pre>
+
<blockquote>
+
<p>The function <tt>undefined_macro</tt> is called whenever a macro definition
was removed successfully.</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 Boost V1.35.0 release. </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 Boost V1.35.0 release. </p>
+
+
<p>The parameter <tt>name</tt> holds the token of the macro which definition was removed.<br>
+
</p>
+
</blockquote>
+
<p><strong><a name="found_warning_directive" id="found_warning_directive"></a>found_warning_drective</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> found_warning_directive(ContextT <span class="keyword">const</span>& ctx,
- ContainerT <span class="keyword">const</span> &message);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> found_warning_directive(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &message);<br></pre>
+
<blockquote>
- <p>The function <tt>found_warning_directive </tt> is called whenever a <span class="preprocessor">#warning </span>directive has been encountered. Note, this function was added for the Boost V1.35.0 release. This function will be called only if the <tt>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</tt> compile time constant was defined to something not equal to zero (see the Compile Time Configuration for more information). </p>
+
+ <p>The function <tt>found_warning_directive </tt> is called whenever a <span class="preprocessor">#warning </span>directive
+has been encountered. Note, this function was added for the Boost
+V1.35.0 release. This function will be called only if the <tt>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</tt> compile time constant was defined to something not equal to zero (see the Compile Time Configuration for more information). </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 parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#warning</span> directive.</p>
+
+
<p>If the return value is <tt>false</tt>, the library throws a preprocessor
exception of the type <code>warning_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#warning</span> directive has been found and the overall directive is replaced by a single newline. </p>
+
</blockquote>
+
<p><strong><a name="found_error_directive" id="found_error_directive"></a>found_error_drective</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">bool</span> found_error_directive(ContextT <span class="keyword">const</span>& ctx,
- ContainerT <span class="keyword">const</span> &message);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> found_error_directive(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &message);<br></pre>
+
<blockquote>
+
<p>The function <tt>found_error_directive </tt> is called whenever a <span class="preprocessor">#error </span>directive has been encountered. Note, this function was added for the Boost V1.35.0 release. </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 parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#error</span> directive.</p>
+
+
<p>If the return value is <tt>false</tt>, the library throws a preprocessor
exception of the type <code>error_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#error</span> directive has been found and the overall directive is replaced by a single newline. </p>
+
</blockquote>
+
<p><strong><a name="found_line_directive" id="found_line_directive"></a>found_line_drective</strong></p>
-<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT>
- <span class="keyword">void</span> found_line_drective(ContextT <span class="keyword">const</span>& ctx,
- ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,
- std::string <span class="keyword">const</span>& filename);
-</pre>
+
+<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> found_line_drective(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,<br> std::string <span class="keyword">const</span>& filename);<br></pre>
+
<blockquote>
+
<p>The function <tt>found_line_directive </tt> is called whenever a <span class="preprocessor">#line </span>directive has been encountered. Note, this function was added for the Boost V1.35.0 release. </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 parameter <tt>arguments</tt> references the argument token sequence of the encountered <span class="preprocessor">#line</span> directive.</p>
+
+
<p>The parameter <tt>line</tt> contains the recognized line number from the <span class="preprocessor">#line</span> directive.</p>
+
+
<p>The parameter <tt>filename</tt> references the recognized file name from the <span class="preprocessor">#line</span> directive (if there was one given).<br>
+
</p>
+
</blockquote>
+
<table border="0">
- <tr>
+
+ <tbody>
+ <tr>
+
<td width="10"></td>
+
<td width="30"></td>
- <td width="30"></td>
+
+ <td width="30"></td>
+
<td width="30"></td>
+
</tr>
+
+ </tbody>
</table>
+
<hr size="1">
<p class="copyright">Copyright © 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>
+
<p class="copyright"><span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Sunday, December 2, 2007 19:12<!-- #EndDate -->
</span></p>
+
</body>
</html>
Modified: branches/release/libs/wave/doc/preface.html
==============================================================================
--- branches/release/libs/wave/doc/preface.html (original)
+++ branches/release/libs/wave/doc/preface.html 2008-07-29 17:37:09 EDT (Tue, 29 Jul 2008)
@@ -1,28 +1,55 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
-<title>Preface</title>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<link href="theme/style.css" rel="stylesheet" type="text/css">
+
+
+ <title>Preface</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
+ <link href="theme/style.css" rel="stylesheet" type="text/css">
</head>
-<body text="#000000" background="theme/bkd.gif">
-<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
- <tr>
- <td width="21"> <h1></h1></td>
+
+<body background="theme/bkd.gif" text="#000000">
+
+<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">Preface</font></b></font></td>
- <td width="96"></td>
+
+ <td width="96"></td>
+
</tr>
+
+ </tbody>
</table>
+
<br>
+
<table border="0">
- <tr>
+
+ <tbody>
+ <tr>
+
<td width="10"></td>
+
<td width="30"></td>
- <td width="30"><img src="theme/l_arr_disabled.gif" width="20" height="19" border="0"></td>
+
+ <td width="30"><img src="theme/l_arr_disabled.gif" border="0" height="19" width="20"></td>
+
<td width="30"></td>
+
</tr>
+
+ </tbody>
</table>
+
<p>During the last time many new features have been developed as additions to the <tt>Spirit</tt>
<a href="references.html#spirit">[4]</a> parser construction framework and we
felt more and more, that it would be very helpful, to have a 'real world' example,
@@ -31,6 +58,7 @@
interest of developers to have a modern, open source C++ preprocessor library
to play with. So we had the idea to implement a C++ preprocessor to fit
this needs - <tt>Wave</tt> was born.</p>
+
<p align="justify">The <tt>Wave</tt> C++ preprocessor library uses the <a href="http://www.boost.org/">
</a> <tt>Spirit[4]</tt> parser construction
library to implement a C++ lexer with ISO/ANSI Standards conformant preprocessing
@@ -38,22 +66,30 @@
token from the input stream. This preprocessed token is generated on the fly
while iterating over the preprocessor iterator sequence (in the terminology
of the STL these iterators are forward iterators). </p>
+
<p align="justify"> The C++ preprocessor is a macro processor that under normal
circumstances is used automatically by your C++ compiler to transform your program
before actual compilation. It is called a macro processor because it allows
to define macros, which are brief abbreviations for longer constructs. The
C++ preprocessor provides four separate facilities that you can use as you see
fit: </p>
+
<blockquote>
- <p><b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"> </b>Inclusion
+
+ <p><b><img src="theme/bullet.gif" id="IMG1" height="13" width="13"> </b>Inclusion
of header files<br>
- <b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"> </b>Macro
+
+ <b><img src="theme/bullet.gif" id="IMG1" height="13" width="13"> </b>Macro
expansion<br>
- <b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"> </b>Conditional
+
+ <b><img src="theme/bullet.gif" id="IMG1" height="13" width="13"> </b>Conditional
compilation<br>
- <b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"> </b>Line
+
+ <b><img src="theme/bullet.gif" id="IMG1" height="13" width="13"> </b>Line
control</p>
+
</blockquote>
+
<p>These features are greatly underestimated today, even more, the preprocessor
has been frowned on for so long that its usage just hasn't been effectively
pushed until the Boost preprocessor library [7]
@@ -61,49 +97,87 @@
generative metaprogramming combined with template metaprogramming in C++ is
by far one of the most powerful compile-time reflection/metaprogramming facilities
that any language has ever supported.</p>
-<p>The C++ Standard [2] was adopted back in 1998, but there is still no (known to me) commercial C++ compiler, which has a bugfree implementation of the rather simple preprocessor requirements mandated therein. This may be a result of the mentioned underestimation or even banning of the preprocessor from good programming style during the last few years or may stem from the somewhat awkward standardese dialect of English used to describe it. Two open source projects are exceptions of this: gcc and Clang (a subproject of LLVM), both providing preprocessors with very good standards conformance. </p>
+
+<p>The C++ Standard [2]
+was adopted back in 1998, but there is still no (known to me)
+commercial C++ compiler, which has a bugfree implementation of the
+rather simple preprocessor requirements mandated therein. This may be a
+result of the mentioned underestimation or even banning of the
+preprocessor from good programming style during the last few years or
+may stem from the somewhat awkward standardese dialect of English used
+to describe it. Two open source projects are exceptions of this: gcc
+and Clang (a subproject of LLVM), both providing preprocessors with
+very good standards conformance. </p>
+
<p align="justify">So the main goals for the <tt>Wave</tt> project are:</p>
+
<blockquote>
- <p><b><img src="theme/bullet.gif" width="13" height="13" id="IMG1"> </b>full
+
+ <p><b><img src="theme/bullet.gif" id="IMG1" height="13" width="13"> </b>full
conformance with the C++ standard (ISO/IEC 14882:1998) [1]
and with the C99 standard (INCITS/ISO/IEC 9899:1999) [2]<br>
- <b><img src="theme/bullet.gif" width="13" height="13"> </b>usage of <tt>Spirit[4]</tt>
+
+ <b><img src="theme/bullet.gif" height="13" width="13"> </b>usage of <tt>Spirit[4]</tt>
for the parsing parts of the game (certainly :-)<br>
- <b><img src="theme/bullet.gif" width="13" height="13"> </b>maximal usage
+
+ <b><img src="theme/bullet.gif" height="13" width="13"> </b>maximal usage
of STL and/or <tt>Boost</tt> libraries (for compactness and maintainability)<br>
- <b><img src="theme/bullet.gif" width="13" height="13"> </b>straightforward
+
+ <b><img src="theme/bullet.gif" height="13" width="13"> </b>straightforward
extendability for the implementation of additional features<br>
- <b><img src="theme/bullet.gif" width="13" height="13"> </b>building a
+
+ <b><img src="theme/bullet.gif" height="13" width="13"> </b>building a
flexible library for different C++ lexing and preprocessing needs</p>
+
</blockquote>
-<p>At the first steps it is not planned to make a very high performance or very
- small C++ preprocessor. If you are looking for these objectives you probably
- have to look at other places. Although our C++ preprocessor iterator works as expected and is usable as a reference implementation, for instance
- for testing of other preprocessor oriented libraries as the Boost Preprocessor
- library [7] et.al. Nevertheless recent work has lead to surprising performance enhancements (if compared
+
+<p>At the first steps it is not planned to make a very high performance
+or very small C++ preprocessor. If you are looking for these objectives
+you probably have to look at other places. Although our C++
+preprocessor iterator works as expected and is usable as a reference
+implementation, for instance for testing of other preprocessor oriented
+libraries as the Boost Preprocessor library [7] et.al. Nevertheless recent work has lead to surprising performance enhancements (if compared
with earlier versions). Wave is still somewhat slower as for instance EDG
based preprocessors (Intel, Comeau) on simple input files, however, as
complexity increases, time dilates expontentially on EDG. Preprocessing time
dilates linearly under Wave, which causes it to easily outperform EDG based
preprocessors when complexity increases.</p>
+
<p>As tests showed, the <tt>Wave</tt> library is very conformant to the C++ Standard,
such that it compiles several strict conformant macro definitions, which are
not even compilable with EDG based preprocessors (i.e. Comeau or Intel). </p>
+
<table border="0">
- <tr>
+
+ <tbody>
+ <tr>
+
<td width="10"></td>
+
<td width="30"></td>
- <td width="30"><img src="theme/l_arr_disabled.gif" width="20" height="19" border="0"></td>
+
+ <td width="30"><img src="theme/l_arr_disabled.gif" border="0" height="19" width="20"></td>
+
<td width="30"></td>
+
</tr>
+
+ </tbody>
</table>
+
<hr size="1">
<p class="copyright">Copyright © 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 19:03<!-- #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