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<></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> include 46 search paths, which define, where to search for files to be included 47 with <tt>#include <...></tt> and <tt>#include "..."</tt> directives<br> 48 <strong><img src="theme/bullet.gif" height="13" width="13"> </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"> </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> <<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> <a href="class_reference_context.html#constructor">context</a>(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 <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> &first, <br> Iterator <span class="keyword">const</span> &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> <<span class="keyword">typename</span> String><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> <<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> <a href="class_reference_context.html#is_defined_macro">is_defined_macro</a>(<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> <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition</a>(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> <a href="class_reference_context.html#reset_macro_definitions">reset_macro_definitions</a>();<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 <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>. 91 </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 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 typedefs 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> &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> 163<p>Constructs a context object on top of the input stream given 164 by the pair of auxilliary iterators <tt>[first, 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">"<Unknown>"</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 "..."</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, 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> &first,<br> Iterator <span class="keyword">const</span> &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 <tt>[first, last)</tt> specifies the input sequence to preprocess. The first version of this 188 function uses the input stream as specified by the constructor. </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 "..."</tt> directives, they are not searched for <tt>#include <file></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 "..."</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 "..."</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 popped 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> <<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> 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> <<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> 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> <<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> 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> // support flags for C++11</span><br> support_option_no_newline_at_end_of_file = 0x20,<br> support_cpp0x = support_option_variadics | support_option_long_long |<br> support_option_no_newline_at_end_of_file | 0x10,<br> support_cpp11 = support_cpp0x, <br><br><span class="comment"> // support flags for C++17</span><br> support_option_has_include = 0x10000,<br> support_cpp1z = support_option_variadics | support_option_long_long |<br> support_option_no_newline_at_end_of_file | support_option_has_include | 0x20000,<br> support_cpp17 = support_cpp1z<br><br><span class="comment"> // support flags for C++20</span><br> support_option_va_opt = 0x40000,<br> support_cpp2a = support_option_variadics | support_option_long_long |<br> support_option_no_newline_at_end_of_file | support_option_has_include |<br> support_option_va_opt | 0x80000,<br> support_cpp20 = support_cpp2a,<br><span class="comment"><br> // the mask for the main language settings</span><br> support_option_mask = 0xFFC0,<br><br><span class="comment"> // additional fine tuning of the general behavior</span><br> 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> 385 <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> 386 <p>The <tt>support_c99</tt> switches on the C99 387 language support, which enables variadics, placemarkers, the <tt>operator _Pragma</tt> and long long suffixes by default. Additionally it disables the C++ 388 specific tokens such as <tt>'->*'</tt>, <tt>'.*'</tt>, <tt>'::'</tt> etc. </p> 389 <p>The <tt>support_option_...</tt> values are to 390 be used in conjunction with the main language settings (<tt>support_normal</tt> and <tt>support_c99</tt>) . </p> 391 <ul> 392 <li>If the <tt>support_option_insert_whitespace</tt> flag is set, the <tt>Wave</tt> library inserts 393 additional whitespace between tokens where the concatenated string 394 representation of the two tokens would form another valid C++ token. 395 This is very important to avoid mis-interpretations of the generated 396 output if it is going to be processed by a C++ compiler afterwards. 397 </li> 398 <li>If the <tt>support_option_preserve_comments</tt> flag is set, the <tt>Wave</tt> library preserves almost 399 all comments in the source code. The only comments not preserved are 400 those contained inside macro definitions. If this flag is not set all 401 comments are replaced by a single space. </li> 402 <li>If the <tt>support_option_no_character_validation</tt> flag is set , the <tt>Wave</tt> library does not validate 403 universal character literals (given in the form of <tt>'u1234'</tt> or <tt>'U12345678'</tt>) to be in the allowed value range. 404 This flag is merely used for internal purposes by the testing framework 405 and will be rarely used by a user of the library.</li> 406 <li>If the <tt>support_option_convert_trigraphs</tt> flag is set, the <tt>Wave</tt> library replaces all 407 occurrences of trigraph characters with their non-trigraph character 408 sequence (i.e. <tt>'??='</tt> is replaced by <tt>'#'</tt> etc.) . By default no replacement is performed. </li> 409 <li>If the <tt>support_option_single_line</tt> flag is set, the <tt>Wave</tt> library will now report an 410 error if the last line of the processed input is not terminated by a 411 new line. This flag is merely used for internal purposes by the testing 412 framework and will be rarely used by a user of the library.</li> 413 <li>If the <tt>support_option_prefer_pp_numbers</tt> flag is set, the <tt>Wave</tt> library is instructed to 414 correctly identify pp-number's in the input stream. These get 415 recognized into 'normal' number tokens before they get returned to the 416 calling application. The flag is set by default and is used merely for 417 internal purposes and will be rarely reset by a user of the library. </li> 418 <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 419 generated token stream, if appropriate. This flag is set by default, to 420 prevent the library from generating <span class="preprocessor">#line</span> directives it must be reset explicitly. </li> 421 <li>If the <span class="keyword">support_option_include_guard_detection</span> flag is set, the <tt>Wave</tt> library will try to 422 automatically identify include guards during the processing of a 423 included file. Files which contained include guards are handled as if 424 they contained a #pragma once, i.e. these files wonn#t be opened twice, 425 even if specified in a second <span class="preprocessor">#include</span> statement. </li> 426 </ul> 427 <blockquote> 428 <p>During this process the library will recognize two forms 429 of include guards:</p> 430 <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> 431 <p> Note, that the parenthesis in the second form are 432 optional (i.e. <tt>!defined INCLUDE_GUARD_MACRO</tt> will 433 work as well). The code allows for any whitespace, newline and single 434 '#' tokens before the <span class="preprocessor">#if</span>/<span class="preprocessor">#ifndef</span> and after the 435 final <span class="preprocessor">#endif</span> for 436 the include guard to be recognized.</p> 437 <p>This flag is on by default, so if you do not want the 438 library to automatically recognize include guards you will need to reset 439 this explicitly. </p> 440 </blockquote> 441 <ul> 442 <li>If the <tt>support_option_emit_pragma_directives</tt> flag is set, the <tt>Wave</tt> library will emit all 443 unknown <span class="preprocessor">#pragma</span> directives to the output. This support option will be recognized only if 444 the <tt>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</tt> is defined 445 during compilation to a value not equal to zero (see <a href="compiletime_config.html">here</a> for more 446 information). </li> 447 <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> 448 </ul> 449 <p><strong> </strong>If the parameter <tt>reset_macros</tt> is true the <tt>set_language</tt> function internally 450 resets the list of defined macros, so please be careful not to call it 451 after you have defined your own macros already. </p> 452</blockquote> 453<p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br> 454 get_max_include_nesting_depth</p> 455<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> 456<blockquote> 457 <p>This functions allow to set or to get the maximal possible 458 include file nesting depth supported by the <tt>Wave</tt> library. The initial value for this is determined by the preprocessing 459 constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt> (see <a href="compiletime_config.html">here</a>).</p> 460</blockquote> 461<table border="0"> 462 <tbody> 463 <tr> 464 <td width="10"></td> 465 <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> 466 <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td> 467 <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td> 468 </tr> 469 </tbody> 470</table> 471<hr size="1"> 472<p class="copyright">Copyright © 2003-2011 Hartmut Kaiser<br> 473 <br> 474 <font size="2">Distributed under the Boost Software 475 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 476 http://www.boost.org/LICENSE_1_0.txt) </font> </p> 477<span class="updated"></span> 478<p class="copyright"><span class="updated">Last 479 updated: 480 <!-- #BeginDate format:fcAm1m -->Saturday, August 6, 2011 20:22<!-- #EndDate --> 481 </span> </p> 482<p> </p> 483</body> 484</html> 485
