ceph/src/boost/libs/wave/doc/class_reference_context.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <title>The Context Object</title>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <link rel="stylesheet" href="theme/style.css" type="text/css">
   7 </head>
   8 <body style="color: rgb(0, 0, 0); background-image: url(theme/bkd.gif);">
   9 <table background="theme/bkd2.gif" border="0" cellspacing="2" width="100%">
  10   <tbody>
  11     <tr>
  12       <td width="21"><h1></h1></td>
  13       <td width="885"><font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The Context Object</font></b></font></td>
  14       <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" align="right" border="0" height="68" width="93"></a></td>
  15     </tr>
  16   </tbody>
  17 </table>
  18 <br>
  19 <table border="0">
  20   <tbody>
  21     <tr>
  22       <td width="10"></td>
  23       <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
  24       <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td>
  25       <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td>
  26     </tr>
  27   </tbody>
  28 </table>
  29 <blockquote>
  30   <p><a href="class_reference_context.html#introduction">Introduction</a><br>
  31     <a href="class_reference_context.html#header_synopsis">Header
  32     'wave/context.hpp' synopsis</a><br>
  33     <a href="class_reference_context.html#public_typedefs">Public
  34     Typedefs</a><br>
  35     <a href="class_reference_context.html#template_parameters">Template
  36     parameters</a><br>
  37     <a href="class_reference_context.html#member_functions">Member
  38     functions</a></p>
  39 </blockquote>
  40 <h2><b><a name="introduction"></a>Introduction</b></h2>
  41 <p>The <tt>boost::wave::context&lt;&gt;</tt> object is the main user visible object of the <tt>Wave</tt> library. It exists to generate the pair of iterators, which while
  42   dereferenced return the preprocessed tokens. Additionally it is used to
  43   control other aspects of the preprocessing, such as </p>
  44 <blockquote>
  45   <p><strong><img id="IMG1" src="theme/bullet.gif" height="13" width="13"></strong>&nbsp;include
  46     search paths, which define, where to search for files to be included
  47     with <tt>#include&nbsp;&lt;...&gt;</tt> and <tt>#include&nbsp;"..."</tt> directives<br>
  48     <strong><img src="theme/bullet.gif" height="13" width="13">&nbsp;</strong>which macros to
  49     predefine and which of the predefined macros to undefine<br>
  50     <strong><img src="theme/bullet.gif" height="13" width="13">&nbsp;</strong>several other options as
  51     for instance to control, whether to enable several extensions to the
  52     C++ Standard (as for instance variadics and placemarkers) or not.</p>
  53 </blockquote>
  54 <h2><b><a name="header_synopsis"></a>Header <a href="http://svn.boost.org/trac/boost/browser/trunk/boost/wave/cpp_context.hpp">wave/cpp_context.hpp</a> synopsis</b></h2>
  55 <pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {<br><span class="keyword">namespace</span> <span class="identifier">wave</span> { <br> <br> <span class="keyword">   struct</span> this_type {};<br><br>    <span class="keyword">template</span> &lt;<br>        <span class="keyword">typename</span> Iterator, <span class="keyword">typename</span> LexIterator, <br>        <span class="keyword">typename</span> InputPolicy, <span class="keyword">typename</span> ContextPolicy,<br>        <span class="keyword">typename</span> Derived = this_type<br>    &gt; <br> <span class="keyword">   class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy <br>    {<br>        <span class="keyword">typedef</span> &lt;unspecified&gt; token_sequence_type;<br><br>    <span class="keyword">public</span>: <br><br> <span class="keyword">       typedef</span> pp_iterator&lt;context&gt; iterator_type; <br>        <span class="keyword">typedef</span> Token token_type;<br>        <span class="keyword">typedef</span> <span class="keyword">typename</span> token_type::position_type position_type;<br>        <span class="keyword">typedef</span> std::list&lt;token_type&gt; token_sequence_type;<br><br><span class="comment">    // constructor</span><br>        <a href="class_reference_context.html#constructor">context</a>(Iterator<span class="keyword"> const</span> &amp;first_, <br>            Iterator <span class="keyword">const</span> &amp;last_, <br>            <span class="keyword">char const</span> *fname = <span class="string">"&lt;Unknown&gt;"</span>,<br>            ContextPolicy <span class="keyword">const</span>&amp; ctx_policy = ContextPolicy())<br><br>    <span class="comment">// iterator interface</span><br>        iterator_type <a href="class_reference_context.html#iterator_interface_begin">begin</a>() <span class="keyword">const</span>;<br>        iterator_type <a href="class_reference_context.html#iterator_interface_begin">begin</a>(Iterator<span class="keyword"> const</span> &amp;first, <br>            Iterator <span class="keyword">const</span> &amp;last) <span class="keyword">const</span>;<br>        iterator_type <a href="class_reference_context.html#iterator_interface_end">end</a>() <span class="keyword">const</span>;<br><br>    <span class="comment">// maintain include paths</span><br><span class="keyword">        bool</span> <a href="class_reference_context.html#add_include_path">add_include_path</a>(<span class="keyword">char const</span> *path_);<br>        <span class="keyword">bool</span> <a href="class_reference_context.html#add_sysinclude_path">add_sysinclude_path</a>(<span class="keyword">char const</span> *path_);<br>        <span class="keyword">void</span> <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter</a>();<br> <br>        size_t <a href="class_reference_context.html#get_iteration_depth">get_iteration_depth</a>() <span class="keyword">const</span>;<br><br> <span class="comment">   // maintain defined macros</span><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword">        bool</span> <a href="class_reference_context.html#add_macro_definition">add_macro_definition</a>(<span class="keyword">String</span> macrostring, <br>        <span class="keyword">    bool</span> is_predefined = <span class="keyword">false</span>);<br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword"></span>        <span class="keyword">bool</span> add_macro_definition(StringT <span class="keyword">const</span> &amp;name, <br>            position_type <span class="keyword">const</span>&amp; pos, <span class="keyword">bool</span> has_params, <br>            std::vector&lt;token_type&gt; &amp;parameters, <br>            token_sequence_type &amp;definition, <br>            <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>)<br><br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_context.html#is_defined_macro">is_defined_macro</a>(<span class="keyword">String const</span> &amp;name) <span class="keyword">const</span>;<br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br>        <span class="keyword">bool</span> <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition</a>(String<span class="keyword"> const</span> &amp;name, <br>        <span class="keyword">    bool</span> even_predefined = <span class="keyword">false</span>);<br>        <span class="keyword">void</span> <a href="class_reference_context.html#reset_macro_definitions">reset_macro_definitions</a>();<br>        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> String&gt;<br> <span class="keyword">       bool</span> <a href="class_reference_context.html#get_macro_definition">get_macro_definition</a>(<br> <span class="keyword">           </span>String<span class="keyword"> const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword"><br>            bool</span> &amp;is_predefined, position_type &amp;pos, <br>            std::vector&lt;token_type&gt; &amp;parameters, <br>            token_sequence_type &amp;definition) <span class="keyword">const</span>; <br><br>        <span class="keyword">typedef</span> &lt;unspecified&gt; macromap_type;<br>        <span class="keyword">typedef</span> typename macromap_type::name_iterator name_iterator;<br>        <span class="keyword">typedef</span> typename macromap_type::const_name_iterator const_name_iterator;<br><br>        name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>();<br>        name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>();<br>        const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>() <span class="keyword">const</span>;<br>        const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>() <span class="keyword">const</span>;<br><br>    <span class="comment">// other options</span><br><span class="keyword">        void</span> <a href="class_reference_context.html#language_support">set_language</a>(language_support enable);<br>        language_support <a href="class_reference_context.html#language_support">get_language</a>() <span class="keyword">const</span>;<br><br><span class="keyword">        void</span> <a href="class_reference_context.html#set_max_include_nesting_depth">set_max_include_nesting_depth</a>(std::size_t new_depth);<br>        size_t <a href="class_reference_context.html#set_max_include_nesting_depth">get_max_include_nesting_depth</a>() <span class="keyword">const</span>;<br><br><span class="comment">    // get the Wave version information </span><br><span class="keyword">        static std::string</span> <a href="class_reference_context.html#get_version">get_version</a>();<br>        <span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version_string</a>();<br>    };<br><br>} <span class="comment">// namespace wave</span><br>} <span class="comment">// namespace boost</span></pre>
  56 <h2><b><a name="template_parameters"></a>Template
  57   parameters</b></h2>
  58 <p>The <tt>boost::wave::context</tt> object has
  59   three template parameters to specify the concrete behaviour of its
  60   operation. The following table describes these with more detail.</p>
  61 <table align="center" border="0" width="90%">
  62   <tbody>
  63     <tr>
  64       <td colspan="2" class="table_title"><b>Template
  65         parameters required for the <tt>boost::wave::context</tt> class </b></td>
  66     </tr>
  67     <tr>
  68       <td class="table_cells" width="32%"><code>Iterator</code></td>
  69       <td class="table_cells" width="68%"><p>The type of the underlying iterator, through which the
  70           input stream is accessed. <br>
  71           This should be at least an <tt>forward_iterator</tt> type
  72           iterator.</p></td>
  73     </tr>
  74     <tr>
  75       <td class="table_cells"><code>LexIterator</code></td>
  76       <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>
  77     </tr>
  78     <tr>
  79       <td class="table_cells"><code>InputPolicy</code></td>
  80       <td class="table_cells"><p>The type of the input policy class, which allows to
  81           customize the behaviour of the Wave library and the type of the
  82           iterators to use, when it comes to including and opening an included
  83           file.</p></td>
  84     </tr>
  85     <tr>
  86       <td class="table_cells"><code>ContextPolicy</code></td>
  87       <td class="table_cells"><p>The type of the context policy class, which allows to
  88           customize different aspects of the behaviour of the preprocessing. The
  89           requirements of this policy and the available customization points
  90           provided by this policy are described <a href="class_reference_ctxpolicy.html">here</a>.&nbsp;&nbsp;
  91           &nbsp;</p></td>
  92     </tr>
  93     <tr class="table_cells">
  94       <td class="table_cells"><code>Derived</code></td>
  95       <td><p>The type of the type being derived from the context type (if
  96           any). This template parameter is optional and defaults to 'this_type',
  97           which means that the context&nbsp;type will be used assuming no derived type exists. <br>
  98         </p></td>
  99     </tr>
 100   </tbody>
 101 </table>
 102 <p>For further information about the lexer type to use, please
 103   refer to the <a href="class_reference_lexer.html">The
 104   Lexer Interface </a>.</p>
 105 <p>If the template parameter <tt>InputPolicy</tt> is
 106   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
 107   to the topic <a href="class_reference_inptpolcy.html">The
 108   Input Policy</a>.</p>
 109 <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
 110   needed for normal (default) execution. For further information about
 111   the context policy, please refer to the topic <a href="class_reference_ctxpolicy.html">The Context Policy</a>. </p>
 112 <h2><a name="public_typedefs"></a>Public
 113   Typedefs</h2>
 114 <p>The <tt>boost::wave::context</tt> template
 115   defines the following public typedefs, which may be useful while using
 116   this class:</p>
 117 <table align="center" border="0" width="90%">
 118   <tbody>
 119     <tr>
 120       <td colspan="2" class="table_title"><b>Public
 121         typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
 122     </tr>
 123     <tr>
 124       <td class="table_cells"><code>iterator_type</code></td>
 125       <td class="table_cells"><p>The <tt>Iterator</tt> template parameter
 126           provided, while the <tt>context</tt> class was
 127           instantiated. </p></td>
 128     </tr>
 129     <tr>
 130       <td class="table_cells"><code>lex_type</code></td>
 131       <td class="table_cells"><p>The <tt>LexIterator</tt> template parameter
 132           provided, while the <tt>context</tt> class was
 133           instantiated. </p></td>
 134     </tr>
 135     <tr>
 136       <td class="table_cells" width="32%"><code>token_type</code></td>
 137       <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>
 138     </tr>
 139     <tr>
 140       <td class="table_cells"><code>input_policy_type</code></td>
 141       <td class="table_cells"><p>The <tt>InputPolicy</tt> template parameter
 142           provided, while the <tt>context</tt> class was
 143           instantiated. </p></td>
 144     </tr>
 145     <tr>
 146       <td class="table_cells"><code>context_policy_type</code></td>
 147       <td class="table_cells"><p>The <tt>ContextPolicy</tt> template
 148           parameter provided, while the <tt>context</tt> class was
 149           instantiated. </p></td>
 150     </tr>
 151     <tr>
 152       <td class="table_cells"><code>position_type</code></td>
 153       <td class="table_cells"><p>The type of the position information contained in every
 154           returned token, which describes the point, at which the given token was
 155           recognised. </p></td>
 156     </tr>
 157   </tbody>
 158 </table>
 159 <h2><b><a name="member_functions"></a>Member
 160   functions</b></h2>
 161 <p><b><a name="constructor" id="constructor"></a>Constructor</b></p>
 162 <pre>    context(Iterator <span class="keyword">const</span> &amp;first, <br>        Iterator <span class="keyword">const</span> &amp;last, <span class="keyword">char</span> <span class="keyword">const</span> *filename, <br>        ContextPolicy <span class="keyword">const</span>&amp; ctx_policy);</pre>
 163 <p>Constructs a context object on top of the input stream given
 164   by the pair of auxilliary iterators <tt>[first,&nbsp;last)</tt>.
 165   The iterators should be at least <tt>forward_iterator</tt> type iterators. The filename parameter is to be supplied for
 166   informational purposes only. This string is used for indicating the
 167   token positions inside the input stream, it is not validated against
 168   the file system. If the filename parameter is not given it defaults to <span class="copyright">"&lt;Unknown&gt;"</span>. If
 169   the ctx_policy parameter isn't supplied it defaults to a default
 170   constructed <tt>ContextPolicy</tt> object. </p>
 171 <p>Additionally the macro symbol table is filled with the
 172   predefined macros and the current reference directory is set to the
 173   path of the given filename. If this filename does not reference valid
 174   file system item, the current reference directory is set to the current
 175   system directory. (The current reference directory is the file system
 176   path, which is used as the target directory during the processing of <tt>#include&nbsp;"..."</tt> directives).</p>
 177 <h3>Iterator interface</h3>
 178 <p>The pair of iterators returned by the <tt>context::begin</tt> and <tt>context::end</tt> functions is the main interface
 179   for accessing the preprocessed tokens from the preprocessor engine.
 180   While iterating over the given iterator range <tt>[begin,&nbsp;end)</tt> there are returned the preprocessed C++ tokens, which are generated on
 181   the fly from the underlying input stream. The returned iterators are
 182   conceptually of <tt>forward_iterator</tt> type.</p>
 183 <p><b><a name="iterator_interface_begin"></a></b><b>begin</b></p>
 184 <pre>    iterator_type begin();<br>    iterator_type begin(Iterator <span class="keyword">const</span> &amp;first,<br>         Iterator <span class="keyword">const</span> &amp;last, <span class="keyword"></span>);</pre>
 185 <blockquote>
 186   <p>Initializes and returns the starting iterator for the
 187     preprocessed token stream. The iterator pair given by the parameters&nbsp; <tt>[first,&nbsp;last)</tt> specifies the input sequence to preprocess. The first version of this
 188     function uses the iinput stream as specified by the constructor.&nbsp;</p>
 189 </blockquote>
 190 <p><b><a name="iterator_interface_end" id="iterator_interface_end"></a></b><b>end</b></p>
 191 <pre>    iterator_type end() <span class="keyword">const</span>;</pre>
 192 <blockquote>
 193   <p>Initializes and returns the end of stream iterator to
 194     compare with for detecting the end of the preprocessed token stream.</p>
 195 </blockquote>
 196 <h3>Maintain include paths</h3>
 197 <p>The <tt>Wave</tt> library maintains two separate
 198   search paths for include files. A search path for user include files
 199   and a search path for system include files. Any directories specified
 200   with the <a href="#add_include_path">add_include_path()</a> function before the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> is called are searched only for the case of <tt>#include&nbsp;"..."</tt> directives, they are not searched for <tt>#include&nbsp;&lt;file&gt;</tt> directives. I.e. these directories are added to the user include search
 201   path. </p>
 202 <p>If additional directories are specified with the <a href="#add_include_path">add_include_path()</a> function after a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>,
 203   these directories are searched for all <tt>#include</tt> directives. I.e. these directories are added to the system include
 204   search path.</p>
 205 <p>In addition, a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> inhibits the use of the current reference directory as the first search
 206   directory for <tt>#include&nbsp;"..."</tt> directives.
 207   Therefore, the current reference directory is searched only, if it is
 208   requested explicitly with a call to the function <a href="#add_include_path">add_include_path(".")</a>. </p>
 209 <p>Callig both functions, the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> and <a href="#add_include_path">add_include_path(".")</a> allows you to control precisely, which directories are searched before
 210   the current one and which are searched after.</p>
 211 <p>These functions are modelled after the command line behaviour
 212   implemented by the popular gcc compiler.<br>
 213 </p>
 214 <p><a name="add_include_path"></a><b>add_include_path</b></p>
 215 <pre> <span class="keyword">   bool</span> add_include_path(<span class="keyword">char const</span> *path);<br>
 216 </pre>
 217 <blockquote>
 218   <p>Adds the given file system path to the user include search
 219     paths. After a call to the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> this function adds the given file system path to the system include
 220     search paths. Note though, that the given path is validated against the
 221     file system. </p>
 222   <p>If the given path string does not form a name of a valid
 223     file system directory item, the function returns <tt>false</tt>.
 224     If the given path was successfully added to the include search paths in
 225     question, the function returns <tt>true</tt>.</p>
 226 </blockquote>
 227 <p><a name="add_sysinclude_path"></a><b>add_sysinclude_path</b></p>
 228 <pre>    <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path);</pre>
 229 <blockquote>
 230   <p>Adds the given file system path to the system include search
 231     paths. This function operates on the system include search path
 232     regardless of the mode of operation of the <a href="#add_include_path">add_include_path()</a>. Note
 233     though, that the given path is validated against the file system.</p>
 234   <p>If the given path string does not form a name of a valid
 235     file system directory item, the function returns <tt>false</tt>.
 236     If the given path was successfully added to the system include search
 237     paths, the function returns <tt>true</tt>.</p>
 238 </blockquote>
 239 <p><a name="set_sysinclude_delimiter"></a><b>set_sysinclude_delimiter</b></p>
 240 <pre> <span class="keyword">   void</span> set_sysinclude_delimiter();</pre>
 241 <blockquote>
 242   <p>Switches the mode, how the <a href="#add_include_path">add_include_path()</a> function operates. By default the given file system path is added to
 243     the user include search paths. After calling this function a subsequent
 244     call to the <a href="#add_include_path">add_include_path()</a> adds the given file system path to the system include search paths.
 245     Additionally it inhibits the the use of the current reference directory
 246     as the first search directory for <tt>#include&nbsp;"..."</tt> directives.</p>
 247 </blockquote>
 248 <p><a name="get_iteration_depth"></a><b>get_iteration_depth</b></p>
 249 <pre>    size_t get_iteration_depth() <span class="keyword">const</span>;</pre>
 250 <blockquote>
 251   <p>Returns the actual include iteration depth, i.e. the current
 252     number of include levels to be poped from the include iteration
 253     context, before the main (topmost) iteration context is reached.</p>
 254 </blockquote>
 255 <h3>Maintain defined macros</h3>
 256 <p><a name="add_macro_definition"></a><b>add_macro_definition</b></p>
 257 <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>
 258 </pre>
 259 <blockquote>
 260   <p>Adds a new macro definition to the macro symbol table. The
 261     parameter <tt>macrostring</tt> should contain the macro to
 262     define in the command line format, i.e. something like <tt>MACRO(x)=definition</tt>.
 263     The following table describes this format in more detail. The parameter <tt>is_predefined</tt> should be true while defining
 264     predefined macros, i.e. macros, which are not undefinable with an <tt>#undef</tt> directive from inside the preprocessed input stream. If this parameter
 265     is not given, it defaults to <tt>false</tt>.</p>
 266   <table align="center" border="0" width="90%">
 267     <tbody>
 268       <tr>
 269         <td colspan="2" class="table_title"><b>Summary
 270           of possible formats for defining macros </b></td>
 271       </tr>
 272       <tr>
 273         <td class="table_cells" width="32%"><code>MACRO</code></td>
 274         <td class="table_cells" width="68%"><code>define <tt>MACRO</tt> as 1</code></td>
 275       </tr>
 276       <tr>
 277         <td class="table_cells"><code>MACRO=</code></td>
 278         <td class="table_cells"><code>define <tt>MACRO</tt> as nothing (empty)</code></td>
 279       </tr>
 280       <tr>
 281         <td class="table_cells"><code>MACRO=definition</code></td>
 282         <td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td>
 283       </tr>
 284       <tr>
 285         <td class="table_cells" width="32%"><code>MACRO(x)</code></td>
 286         <td class="table_cells" width="68%"><code>define <tt>MACRO(x)</tt> as 1</code></td>
 287       </tr>
 288       <tr>
 289         <td class="table_cells"><code>MACRO(x)=</code></td>
 290         <td class="table_cells"><code>define <tt>MACRO(x)</tt> as nothing (empty)</code></td>
 291       </tr>
 292       <tr>
 293         <td class="table_cells"><code>MACRO(x)=definition</code></td>
 294         <td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td>
 295       </tr>
 296     </tbody>
 297   </table>
 298   <p>The function returns <tt>false</tt>, if the
 299     macro to define already was defined and the new definition is
 300     equivalent to the existing one, it returns true, if the new macro was
 301     successfully added to the macro symbol table.</p>
 302   <p>If the given macro definition resembles a redefinition and
 303     the new macro is not identical to the already defined macro (in the
 304     sense defined by the C++ Standard), the function throws a corresponding <tt>preprocess_exception</tt>.</p>
 305 </blockquote>
 306 <p><a name="is_defined_macro"></a><b>is_defined_macro</b></p>
 307 <pre> <span class="keyword">   template</span> &lt;<span class="keyword">typename</span> String&gt;<br>    <span class="keyword">bool</span> is_defined_macro(String <span class="keyword">const</span> &amp;name) <span class="keyword">const</span>; </pre>
 308 <blockquote>
 309   <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>
 310 </blockquote>
 311 <p><strong><a name="get_macro_definition"></a>get_macro_definition</strong></p>
 312 <pre> <span class="keyword">   template</span> &lt;<span class="keyword">typename</span> String&gt;<br>    <span class="keyword">bool</span> get_macro_definition(<br> <span class="keyword">       </span>String<span class="keyword"> const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword"><br>        bool</span> &amp;is_predefined, position_type &amp;pos, <br>        std::vector&lt;token_type&gt; &amp;parameters, <br>        token_sequence_type &amp;definition) <span class="keyword">const</span>; </pre>
 313 <blockquote>
 314   <p>Allows to retrieve all information known with regard to a
 315     macro definition. The parameter <tt>name</tt> specifies
 316     the name of the macro the information should be returned for. The
 317     parameters <tt>is_function_style</tt> and <tt>is_predefined</tt> return, whether the macro has been defined as a function style macro or
 318     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
 319     the parameter <tt>definition</tt> will contain the token
 320     sequence for the definition (macro body).</p>
 321   <p>The function returns <tt>true</tt> is the macro
 322     was defined and the requested information has been successfully
 323     retrieved, <tt>false</tt> otherwise.</p>
 324 </blockquote>
 325 <p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p>
 326 <pre><span class="keyword"> </span> <span class="keyword">  template</span> &lt;<span class="keyword">typename</span> String&gt;<br><span class="keyword">    bool</span> remove_macro_definition(<br>        String<span class="keyword"> const</span> &amp;name, <span class="keyword">bool</span> even_predefined); </pre>
 327 <blockquote>
 328   <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
 329     input stream. If the parameter <tt>even_predefined</tt> is <tt>true</tt>, then the macro is removed from the macro
 330     symbol table even, if it is defined as a predefined macro. </p>
 331   <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>
 332   <p>The function returns <tt>false</tt>, if the
 333     macro to undefine was not defined and returns <tt>true</tt> otherwise.</p>
 334   <p>If the macro to remove may not be undefined (it is a
 335     predefined macro and the parameter <tt>even_predefined</tt> is set to <tt>false</tt> or it is one of the mentioned not
 336     undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p>
 337 </blockquote>
 338 <p><a name="reset_macro_definitions"></a><b>reset_macro_definitions</b></p>
 339 <pre><span class="keyword">    void</span> reset_macro_definitions(); </pre>
 340 <blockquote>
 341   <p>Resets the macro symbol table to it's initial state, i.e.
 342     undefines all user defined macros and inserts the internal predefined
 343     macros as described <a href="predefined_macros.html">here</a>.</p>
 344 </blockquote>
 345 <p><a name="macro_names_iterators"></a><b>macro_names_begin,
 346   macro_names_end </b></p>
 347 <pre>    name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>();<br>    name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>();<br>    const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>() <span class="keyword">const</span>;<br>    const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>() <span class="keyword">const</span>;<br>
 348 </pre>
 349 <blockquote>
 350   <p>The <tt>macro_names_begin</tt> and <tt>macro_names_end</tt> functions return iterators allowing to iterate on the names of all
 351     defined macros.</p>
 352 </blockquote>
 353 <h3><a name="get_version"></a>Get Version
 354   information</h3>
 355 <p><b>get_version</b></p>
 356 <pre><span class="keyword"> </span><span class="keyword">   static std::string</span> get_version(); </pre>
 357 <blockquote>
 358   <p>Returns a string containing the current Wave version
 359     formatted as <span class="string">0xvvrsbbbb</span> (this is a string representation of the equivalent hexadecimal number),
 360     where <span class="literal">'vv'</span> is the
 361     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
 362     is the same as is inserted in the preprocessed token stream, when the
 363     predefined macro <tt>__WAVE_VERSION__</tt> is expanded.</p>
 364 </blockquote>
 365 <p><b>get_version_str</b></p>
 366 <pre><span class="keyword"> </span><span class="keyword">   static std::string</span> get_version_str(); </pre>
 367 <blockquote>
 368   <p>Returns a string containing the current Wave version
 369     formatted as <span class="string">"v.rr.ss.bbbb"</span>,
 370     where <span class="literal">'v'</span> is the
 371     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
 372     is the same as it will be inserted in the preprocessed token stream,
 373     when the predefined macro <tt>__WAVE_VERSION_STR__</tt> is
 374     expanded.</p>
 375 </blockquote>
 376 <h3>Control extended options</h3>
 377 <p><a name="language_support"></a>set_language<br>
 378   get_language</p>
 379 <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>
 380 <blockquote>
 381   <p>This functions allows to specify the language mode, in which
 382     the <tt>Wave</tt> library should work. The possible
 383     language modes are defined by the enumerated type <tt>language_support</tt>:</p>
 384   <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 = 0xFFB0,<br><br><span class="comment">    // additional fine tuning of the general behavior</span>
 385         support_option_emit_contline = 0x0040,<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_directives = 0x2000,<br>        support_option_include_guard_detection = 0x4000,<br>        support_option_emit_pragma_directives = 0x8000<br>    };</pre>
 386   <p>When used with <tt>support_option_variadics</tt> the support for variadics, placemarkers and the <tt>operator&nbsp;_Pragma()</tt> is enabled in normal C++ mode. When used with the <tt>support_option_long_long</tt> the support for long long suffixes is enabled in C++ mode. </p>
 387   <p>The <tt>support_c99</tt> switches on the C99
 388     language support, which enables variadics, placemarkers, the <tt>operator&nbsp;_Pragma</tt> and long long suffixes by default. Additionally it disables the C++
 389     specific tokens such as <tt>'-&gt;*'</tt>, <tt>'.*'</tt>, <tt>'::'</tt> etc. </p>
 390   <p>The <tt>support_option_...</tt> values are to
 391     be used in conjunction with the main language settings (<tt>support_normal</tt> and <tt>support_c99</tt>) . </p>
 392   <ul>
 393     <li>If the <tt>support_option_insert_whitespace</tt> flag is set,&nbsp;the <tt>Wave</tt> library &nbsp;inserts
 394       additional whitespace between tokens where the concatenated string
 395       representation of the two tokens would form another valid C++ token.
 396       This is very importatnt to avoid mis-interpretations of the generated
 397       output if it is going to be processed by a C++ compiler afterwards.
 398       &nbsp; </li>
 399     <li>If the <tt>support_option_preserve_comments</tt> flag is set, the <tt>Wave</tt> library preserves almost
 400       all comments in the source code. The only comments not preserved are
 401       those contained inside macro definitions. If this flag is not set all
 402       comments are replaced by a single space. </li>
 403     <li>If the <tt>support_option_no_character_validation</tt> flag is set , the <tt>Wave</tt> library does not validate
 404       universal character literals (given in the form of <tt>'u1234'</tt> or <tt>'U12345678'</tt>) to be in the allowed value range.
 405       This flag is merely used for internal purposes by the testing framework
 406       and will be rarely used by a user of the library.</li>
 407     <li>If the <tt>support_option_convert_trigraphs</tt> flag is set, the <tt>Wave</tt> library replaces all
 408       occurences of trigraph characters with their non-trigraph character
 409       sequence (i.e. <tt>'??='</tt> is replaced by <tt>'#'</tt> etc.) . By default no replacement is performed. </li>
 410     <li>If the <tt>support_option_single_line</tt> flag is set, the <tt>Wave</tt> library will now reprot an
 411       error if the last line of the processed input is not terminated by a
 412       new line. This flag is merely used for internal purposes by the testing
 413       framework and will be rarely used by a user of the library.</li>
 414     <li>If the <tt>support_option_prefer_pp_numbers</tt> flag is set, the <tt>Wave</tt> library is instructed to
 415       correctly identify pp-number's in the input stream. These get
 416       recognized into 'normal' number tokens before they get returned to the
 417       calling application. The flag is set by default and is used merely for
 418       internal purposes and will be rarely reset by a user of the library. </li>
 419     <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
 420       generated token stream, if appropriate. This flag is set by default, to
 421       prevent the library from generating <span class="preprocessor">#line</span> directives it must be reset explicitely. </li>
 422     <li>If the <span class="keyword">support_option_include_guard_detection</span> flag is set, the <tt>Wave</tt> library will try to
 423       automatically identify include guards during the processing of a
 424       included file. Files which contained include guards are handled as if
 425       they contained a #pragma once, i.e. these files wonn#t be opened twice,
 426       even if specified in a second <span class="preprocessor">#include</span> statement. </li>
 427   </ul>
 428   <blockquote>
 429     <p>During this process the library will recognize two forms
 430       of include guards:</p>
 431     <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>
 432     <p> Note, that the parenthesis in the second form are
 433       optional (i.e. <tt>!defined INCLUDE_GUARD_MACRO</tt> will
 434       work as well). The code allows for any whitespace, newline and single
 435       '#' tokens before the <span class="preprocessor">#if</span>/<span class="preprocessor">#ifndef</span> and after the
 436       final <span class="preprocessor">#endif</span> for
 437       the include guard to be recognized.</p>
 438     <p>This flag is on by default, so if you do not want the
 439       library to automatically reconize include guards you will need to reset
 440       this explicitely. </p>
 441   </blockquote>
 442   <ul>
 443     <li>If the <tt>support_option_emit_pragma_directives</tt> flag is set, the <tt>Wave</tt> library will emit all
 444       unknown <span class="preprocessor">#pragma</span> directives to the output. This suport option will be recognized only if
 445       the <tt>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</tt> is defined
 446       during compilation to a value not equal to zero (see <a href="compiletime_config.html">here</a> for more
 447       information). </li>
 448     <li>If the <tt>support_option_emit_contlines</tt> flag is set, the <tt>Wave</tt> library will emit all backslash newline sequences encountered in the input. It will generate a <tt>T_CONTLINE</tt> token for each of those character sequences. Please note that this option is supported by the custom SLex lexer module only. See the cpp_tokens example for a working example.</li>
 449   </ul>
 450   <p><strong> </strong>If the parameter <tt>reset_macros</tt> is true the <tt>set_language</tt> function internally
 451     resets the list of defined macros, so please be careful not to call it
 452     after you have defined your own macros already. </p>
 453 </blockquote>
 454 <p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br>
 455   get_max_include_nesting_depth</p>
 456 <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>
 457 <blockquote>
 458   <p>This functions allow to set or to get the maximal possible
 459     include file nesting depth supported by the <tt>Wave</tt> library. The initial value for this is determined by the preprocessing
 460     constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt> (see <a href="compiletime_config.html">here</a>).</p>
 461 </blockquote>
 462 <table border="0">
 463   <tbody>
 464     <tr>
 465       <td width="10"></td>
 466       <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
 467       <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td>
 468       <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td>
 469     </tr>
 470   </tbody>
 471 </table>
 472 <hr size="1">
 473 <p class="copyright">Copyright &copy; 2003-2011 Hartmut Kaiser<br>
 474   <br>
 475   <font size="2">Distributed under the Boost Software
 476   License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 477   http://www.boost.org/LICENSE_1_0.txt) </font> </p>
 478 <span class="updated"></span>
 479 <p class="copyright"><span class="updated">Last
 480   updated:
 481   <!-- #BeginDate format:fcAm1m -->Saturday, August 6, 2011  20:22<!-- #EndDate -->
 482   </span> </p>
 483 <p>&nbsp;</p>
 484 </body>
 485 </html>