Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/wave/doc/class_reference_context.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 34.3 KB
Line 
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"></head>
7    <body text="#000000" background="theme/bkd.gif">
8<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
9  <tr> 
10    <td width="21"> <h1></h1></td>
11    <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The
12      Context Object</font></b></font></td>
13    <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
14  </tr>
15</table>
16<br>
17  <table border="0">
18    <tr> 
19      <td width="10"></td>
20      <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
21      <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
22      <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td>
23    </tr>
24  </table>
25<blockquote> 
26  <p><a href="class_reference_context.html#introduction">Introduction</a><br>
27    <a href="class_reference_context.html#header_synopsis">Header 'wave/context.hpp' synopsis</a><br>
28        <a href="class_reference_context.html#public_typedefs">Public Typedefs</a><br>
29    <a href="class_reference_context.html#template_parameters">Template parameters</a><br>
30    <a href="class_reference_context.html#member_functions">Member functions</a></p>
31  </blockquote>
32<h2><b><a name="introduction"></a>Introduction</b></h2>
33<p>The <tt>boost::wave::context&lt;&gt;</tt> object is the main user visible object of
34  the <tt>Wave</tt> library. It exists to generate the pair of iterators, which
35  while dereferenced return the preprocessed tokens. Additionally it is used
36  to control other aspects of the preprocessing, such as </p>
37<blockquote> 
38  <p><STRONG><IMG id="IMG1" height="13" src="theme/bullet.gif" width="13"></STRONG>&nbsp;include
39    search paths, which define, where to search for files to be included with
40    <tt>#include&nbsp;&lt;...&gt;</tt> and <tt>#include&nbsp;"..."</tt> directives<br>
41    <STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>which
42    macros to predefine and which of the predefined macros to undefine<br>
43    <STRONG><img src="theme/bullet.gif" width="13" height="13">&nbsp;</STRONG>several
44    other options as for instance to control, whether to enable several extensions
45    to the C++ Standard (as for instance variadics and placemarkers) or not.</p>
46</blockquote>
47<h2><b><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/viewcvs.py/boost/boost/boost/wave/cpp_context.hpp?view=markup">wave/cpp_context.hpp</a> 
48  synopsis</b></h2>
49<pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {
50<span class="keyword">namespace</span> <span class="identifier">wave</span> {
51   
52    <span class="keyword">template</span> &lt;
53        <span class="keyword">typename</span> Iterator, <span class="keyword">typename</span> LexIterator,
54        <span class="keyword">typename</span> InputPolicy, <span class="keyword">typename</span> TracePolicy
55    &gt; 
56    <span class="keyword">class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy
57    {
58    <span class="keyword">public</span>:
59
60        <span class="keyword">typedef</span> pp_iterator&lt;context&gt; iterator_type;
61        <span class="keyword">typedef</span> Token token_type;
62        <span class="keyword">typedef</span> <span class="keyword">typename</span> token_type::position_type position_type;
63        <span class="keyword">typedef</span> std::list&lt;token_type&gt; token_sequence_type;<br>
64    <span class="comment">// constructor</span>
65        <a href="class_reference_context.html#constructor">context</a>(Iterator<span class="keyword"> const</span> &amp;first_,
66            Iterator <span class="keyword">const</span> &amp;last_,
67            <span class="keyword">char const</span> *fname = <span class="string">"&lt;Unknown&gt;"</span>,
68            TracePolicy <span class="keyword">const</span>&amp; trace = TracePolicy())
69
70    <span class="comment">// iterator interface</span>
71        iterator_type <a href="class_reference_context.html#iterator_interface_begin">begin</a>() <span class="keyword">const</span>;
72        iterator_type <a href="class_reference_context.html#iterator_interface_end">end</a>() <span class="keyword">const</span>;
73
74    <span class="comment">// maintain include paths</span>
75        <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_);
76        <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_);
77        <span class="keyword">void</span> <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter</a>();
78 
79        size_t <a href="class_reference_context.html#get_iteration_depth">get_iteration_depth</a>() <span class="keyword">const</span>;
80
81    <span class="comment">// maintain defined macros</span>
82        <span class="keyword">bool</span> <a href="class_reference_context.html#add_macro_definition">add_macro_definition</a>(<span class="keyword">std::string</span> macrostring,
83            <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>);
84        <span class="keyword">bool</span> <a href="class_reference_context.html#is_defined_macro">is_defined_macro</a>(<span class="keyword">std::string const</span> &amp;name) <span class="keyword">const</span>;
85        <span class="keyword">bool</span> <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition</a>(<span class="keyword">std::string const</span> &amp;name,
86            <span class="keyword">bool</span> even_predefined = <span class="keyword">false</span>);
87        <span class="keyword">void</span> <a href="class_reference_context.html#reset_macro_definitions">reset_macro_definitions</a>();
88    <span class="keyword">    bool</span></span> <a href="class_reference_context.html#get_macro_definition">get_macro_definition</a>(
89        <span class="keyword">    std::string const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword">
90            bool</span> &amp;is_predefined, position_type &amp;pos,
91            std::vector&lt;token_type&gt; &amp;parameters,
92            token_sequence_type &amp;definition) <span class="keyword">const</span>;
93
94    <span class="comment">// other options</span>
95        <span class="keyword">void</span> <a href="class_reference_context.html#language_support">set_language</a>(language_support enable);
96        language_support <a href="class_reference_context.html#language_support">get_language</a>() <span class="keyword">const</span>;<br>
97        <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>
98    <span class="comment">// get the Wave version information </span>
99        <span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version</a>();
100        <span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version_string</a>();
101    };
102
103}   <span class="comment">// namespace wave</span>
104}   <span class="comment">// namespace boost</span></pre>
105<h2><b><a name="template_parameters"></a>Template parameters</b></h2>
106<p>The <tt>boost::wave::context</tt> object has three template parameters to specify
107  the concrete behaviour of its operation. The following table describes these
108  with more detail.</p>
109<table width="90%" border="0" align="center">
110  <tr> 
111    <td colspan="2" class="table_title"><b>Template parameters required for the
112      <tt>boost::wave::context</tt> class </b></td>
113  </tr>
114  <tr> 
115    <td width="32%" class="table_cells"><code>Iterator</code></td>
116    <td width="68%" class="table_cells"><p>The type of the underlying iterator,
117        through which the input stream is accessed. <br>
118        This should be at least an <tt>forward_iterator</tt> type iterator.</p></td>
119  </tr>
120  <tr> 
121    <td class="table_cells"><code>LexIterator</code></td>
122    <td class="table_cells"><p>The type of the lexer type to be used by the <tt>Wave</tt> 
123        library to identify tokens in the input stream.</p></td>
124  </tr>
125  <tr> 
126    <td class="table_cells"><code>InputPolicy</code></td>
127    <td class="table_cells"><p>The type of the input policy class, which allows
128        to customize the behaviour of the Wave library and the type of the iterators
129        to use, when it comes to including and opening an included file.</p></td>
130  </tr>
131  <tr>
132    <td class="table_cells"><code>TracePolicy</code></td>
133    <td class="table_cells"><p>The type of the trace policy class, which allows
134        to customize the trace output generated while expanding macros. The requirements for this policy are described <a href="class_reference_ctxpolicy.html">here</a>.</p></td>
135  </tr>
136</table>
137<p>For further information about the lexer type to use, please refer to the <a href="class_reference_lexer.html">The
138  Lexer Interface </a>.</p>
139<p>If the template parameter <tt>InputPolicy</tt> is omitted, the template <tt>boost::wave::iteration_context_policies::load_file_to_string</tt> 
140  is used. For further information about the input policy, please refer to the
141  topic <a href="class_reference_inptpolcy.html">The Input Policy</a>.</p>
142<p>If the template parameter TracePolicyT is omitted, the <tt>boost::wave::macro_trace_policies::no_tracing</tt> 
143  policy type is used, i.e. by default there is no tracing performed. For further
144  information about the hooking policy, please refer to the topic <a href="class_reference_ctxpolicy.html">The
145  Context Policy</a>. </p>
146<h2><a name="public_typedefs"></a>Public Typedefs</h2>
147<p>The <tt>boost::wave::context</tt> template defines the following public typedefs, which may be useful while using this class:</p>
148<table width="90%" border="0" align="center">
149  <tr>
150    <td colspan="2" class="table_title"><b>Public typedef's defined by the <tt>boost::wave::context</tt> class </b></td>
151  </tr>
152  <tr>
153    <td class="table_cells"><code>iterator_type</code></td>
154    <td class="table_cells"><p>The <tt>Iterator</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
155  </tr>
156  <tr>
157    <td class="table_cells"><code>lex_type</code></td>
158    <td class="table_cells"><p>The <tt>LexIterator</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
159  </tr>
160  <tr>
161    <td width="32%" class="table_cells"><code>token_type</code></td>
162    <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>
163  </tr>
164  <tr>
165    <td class="table_cells"><code>input_policy_type</code></td>
166    <td class="table_cells"><p>The <tt>InputPolicy</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
167  </tr>
168  <tr>
169    <td class="table_cells"><code>trace_policy_type</code></td>
170    <td class="table_cells"><p>The <tt>TracePolicy</tt> template parameter provided, while the <tt>context</tt> class was instantiated. </p></td>
171  </tr>
172  <tr>
173    <td class="table_cells"><code>position_type</code></td>
174    <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>
175  </tr>
176</table>
177<h2><b><a name="member_functions"></a>Member functions</b></h2>
178<p><b><a name="constructor" id="constructor"></a>Constructor</b></p>
179<pre>    context(Iterator <span class="keyword">const</span> &amp;first,
180        Iterator <span class="keyword">const</span> &amp;last, <span class="keyword">char</span> <span class="keyword">const</span> *filename,
181        TracePolicy <span class="keyword">const</span>&amp; trace);</pre> 
182    <p>Constructs a context object on top of the input stream given by the pair
183    of auxilliary iterators <tt>[first,&nbsp;last)</tt>. The iterators should
184    be at least <tt>forward_iterator</tt> type iterators. The filename parameter
185    is to be supplied for informational purposes only. This string is used for
186    indicating the token positions inside the input stream, it is not validated
187    against the file system. If the filename parameter is not given it defaults
188    to <span class="copyright">&quot;&lt;Unknown&gt;&quot;</span>. If the trace
189    parameter isn't supplied it defaults to a default constructed <tt>TracePolicy</tt> 
190    object. </p>
191    <p>Additionally the macro symbol table is filled with the predefined macros
192    and the current reference directory is set to the path of the given filename.
193    If this filename does not reference valid file system item, the current reference
194    directory is set to the current system directory. (The current reference directory
195    is the file system path, which is used as the target directory during the
196    processing of <tt>#include&nbsp;&quot;...&quot;</tt> directives).</p>
197  <h3>Iterator interface</h3>
198<p>The pair of iterators returned by the <tt>context::begin</tt> and <tt>context::end</tt> 
199  functions is the main interface for accessing the preprocessed tokens from the
200  preprocessor engine. While iterating over the given iterator range <tt>[begin,&nbsp;end)</tt> 
201  there are returned the preprocessed C++ tokens, which are generated on the fly
202  from the underlying input stream. The returned iterators are conceptually of
203  <tt>forward_iterator</tt> type.</p>
204<p><b><a name="iterator_interface_begin"></a></b><b>begin</b></p>
205<pre>    iterator_type begin();</pre>
206<blockquote>
207  <p>Initializes and returns the starting iterator for the preprocessed token
208    stream.</p>
209 
210</blockquote>
211<p><b><a name="iterator_interface_end" id="iterator_interface_end"></a></b><b>end</b></p>
212<pre>    iterator_type end() <span class="keyword">const</span>;</pre>
213<blockquote> 
214  <p>Initializes and returns the end of stream iterator to compare with for detecting
215    the end of the preprocessed token stream.</p>
216</blockquote>
217<h3>Maintain include paths</h3>
218<p>The <tt>Wave</tt> library maintains two separate search paths for include
219  files. A search path for user include files and a search path for system include
220  files. Any directories specified with the <a href="#add_include_path">add_include_path()</a> 
221  function before the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> 
222  is called are searched only for the case of <tt>#include&nbsp;&quot;...&quot;</tt> 
223  directives, they are not searched for <tt>#include&nbsp;&lt;file&gt;</tt> directives.
224  I.e. these directories are added to the user include search path. </p>
225<p>If additional directories are specified with the <a href="#add_include_path">add_include_path()</a> 
226  function after a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>,
227  these directories are searched for all <tt>#include</tt> directives. I.e. these
228  directories are added to the system include search path.</p>
229<p>In addition, a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> 
230  inhibits the use of the current reference directory as the first search directory
231  for <tt>#include&nbsp;&quot;...&quot;</tt> directives. Therefore, the current
232  reference directory is searched only, if it is requested explicitly with a call
233  to the function <a href="#add_include_path">add_include_path(&quot;.&quot;)</a>.
234</p>
235<p>Callig both functions, the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> 
236  and <a href="#add_include_path">add_include_path(&quot;.&quot;)</a> allows you
237  to control precisely, which directories are searched before the current one
238  and which are searched after.</p>
239<p>These functions are modelled after the command line behaviour implemented by
240  the popular gcc compiler.<br>
241</p>
242<p><a name="add_include_path"></a><b>add_include_path</b></p>
243<pre>    <span class="keyword">bool</span> add_include_path(<span class="keyword">char const</span> *path);
244</pre>
245<blockquote> 
246  <p>Adds the given file system path to the user include search paths. After a
247    call to the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> 
248    this function adds the given file system path to the system include search
249    paths. Note though, that the given path is validated against the file system.
250  </p>
251  <p>If the given path string does not form a name of a valid file system directory
252    item, the function returns <tt>false</tt>. If the given path was successfully
253    added to the include search paths in question, the function returns <tt>true</tt>.</p>
254</blockquote>
255<p><a name="add_sysinclude_path"></a><b>add_sysinclude_path</b></p>
256<pre>    <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path);</pre>
257<blockquote> 
258  <p>Adds the given file system path to the system include search paths. This
259    function operates on the system include search path regardless of the mode
260    of operation of the <a href="#add_include_path">add_include_path()</a>. Note
261    though, that the given path is validated against the file system.</p>
262  <p>If the given path string does not form a name of a valid file system directory
263    item, the function returns <tt>false</tt>. If the given path was successfully
264    added to the system include search paths, the function returns <tt>true</tt>.</p>
265</blockquote>
266<p><a name="set_sysinclude_delimiter"></a><b>set_sysinclude_delimiter</b></p>
267<pre>    <span class="keyword">void</span> set_sysinclude_delimiter();</pre>
268<blockquote> 
269  <p>Switches the mode, how the <a href="#add_include_path">add_include_path()</a> 
270    function operates. By default the given file system path is added to the user
271    include search paths. After calling this function a subsequent call to the
272    <a href="#add_include_path">add_include_path()</a> adds the given file system
273    path to the system include search paths. Additionally it inhibits the the
274    use of the current reference directory as the first search directory for <tt>#include&nbsp;&quot;...&quot;</tt> 
275    directives.</p>
276</blockquote>
277<p><a name="get_iteration_depth"></a><b>get_iteration_depth</b></p>
278<pre>    size_t get_iteration_depth() <span class="keyword">const</span>;</pre>
279<blockquote> 
280  <p>Returns the actual include iteration depth, i.e. the current number of include
281    levels to be poped from the include iteration context, before the main (topmost)
282    iteration context is reached.</p>
283</blockquote>
284<h3>Maintain defined macros</h3>
285<p><a name="add_macro_definition"></a><b>add_macro_definition</b></p>
286<pre><span class="keyword">    bool</span> add_macro_definition(
287        <span class="keyword">std::string</span> macrostring,
288        bool is_predefined);
289</pre>
290<blockquote> 
291  <p>Adds a new macro definition to the macro symbol table. The parameter <tt>macrostring</tt> 
292    should contain the macro to define in the command line format, i.e. something
293    like <tt>MACRO(x)=definition</tt>. The following table describes this format
294    in more detail. The parameter <tt>is_predefined</tt> should be true while
295    defining predefined macros, i.e. macros, which are not undefinable with an
296    <tt>#undef</tt> directive from inside the preprocessed input stream. If this
297    parameter is not given, it defaults to <tt>false</tt>.</p>
298  <table width="90%" border="0" align="center">
299    <tr> 
300      <td colspan="2" class="table_title"><b>Summary of possible formats for defining
301        macros </b></td>
302    </tr>
303    <tr> 
304      <td width="32%" class="table_cells"><code>MACRO</code></td>
305      <td width="68%" class="table_cells"><code>define <tt>MACRO</tt> as 1</code></td>
306    </tr>
307    <tr> 
308      <td class="table_cells"><code>MACRO=</code></td>
309      <td class="table_cells"><code>define <tt>MACRO</tt> as nothing (empty)</code></td>
310    </tr>
311    <tr> 
312      <td class="table_cells"><code>MACRO=definition</code></td>
313      <td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td>
314    </tr>
315    <tr> 
316      <td width="32%" class="table_cells"><code>MACRO(x)</code></td>
317      <td width="68%" class="table_cells"><code>define <tt>MACRO(x)</tt> as 1</code></td>
318    </tr>
319    <tr> 
320      <td class="table_cells"><code>MACRO(x)=</code></td>
321      <td class="table_cells"><code>define <tt>MACRO(x)</tt> as nothing (empty)</code></td>
322    </tr>
323    <tr> 
324      <td class="table_cells"><code>MACRO(x)=definition</code></td>
325      <td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td>
326    </tr>
327  </table>
328  <p>The function returns <tt>false</tt>, if the macro to define already was defined
329    and the new definition is equivalent to the existing one, it returns true,
330    if the new macro was successfully added to the macro symbol table.</p>
331  <p>If the given macro definition resembles a redefinition and the new macro
332    is not identical to the already defined macro (in the sense defined by the
333    C++ Standard), the function throws a corresponding <tt>preprocess_exception</tt>.</p>
334</blockquote>
335<p><a name="is_defined_macro"></a><b>is_defined_macro</b></p>
336<pre><span class="keyword">    bool</span> is_defined_macro(<span class="keyword">std::string const</span> &amp;name) <span class="keyword">const</span>; </pre>
337<blockquote>
338  <p>Returns, if a macro with the given <tt>name</tt> is defined, i.e. if it is
339    contained in the macro symbol table.</p>
340  </blockquote>
341<p><strong><a name="get_macro_definition"></a>get_macro_definition</strong></p>
342<pre>    <span class="keyword">bool</span></span> get_macro_definition(
343        <span class="keyword">std::string const</span> &amp;name, <span class="keyword">bool</span> &amp;is_function_style, <span class="keyword">
344        bool</span> &amp;is_predefined, position_type &amp;pos,
345        std::vector&lt;token_type&gt; &amp;parameters,
346        token_sequence_type &amp;definition) <span class="keyword">const</span>; </pre>
347<blockquote>
348  <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
349  <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>
350  <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>
351</blockquote>
352<p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p>
353<pre><span class="keyword">    bool</span> remove_macro_definition(
354        <span class="keyword">std::string const</span> &amp;name,
355        <span class="keyword">bool</span> even_predefined); </pre>
356<blockquote>
357  <p>Removes the definition of the macro with the given <tt>name</tt> from the
358    macro symbol table. This operation is equivalent to an <tt>#undef</tt> directive
359    with this <tt>name</tt> executed from within the input stream. If the parameter
360    <tt>even_predefined</tt> is <tt>true</tt>, then the macro is removed from
361    the macro symbol table even, if it is defined as a predefined macro. </p>
362  <p>Note though, that the following macros are <b>not</b> undefinable in any
363    case: <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt>,
364    <tt>__cplusplus</tt>, <tt>__STDC__</tt>. If the parameter <tt>even_predefined</tt> 
365    is not given, it defaults to <tt>false</tt>.</p>
366  <p>The function returns <tt>false</tt>, if the macro to undefine was not defined
367    and returns <tt>true</tt> otherwise.</p>
368  <p>If the macro to remove may not be undefined (it is a predefined macro and
369    the parameter <tt>even_predefined</tt> is set to <tt>false</tt> or it is one
370    of the mentioned not undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p>
371</blockquote>
372<p><a name="reset_macro_definitions"></a><b>reset_macro_definitions</b></p>
373<pre><span class="keyword">    void</span> reset_macro_definitions(); </pre>
374<blockquote>
375  <p>Resets the macro symbol table to it's initial state, i.e. undefines all user defined macros and inserts the internal predefined macros as described <a href="predefined_macros.html">here</a>.</p>
376</blockquote>
377<h3><a name="get_version"></a>Get Version information</h3>
378<p><b>get_version</b></p>
379<pre><span class="keyword">    </span><span class="keyword">static std::string</span> get_version(); </pre>
380<blockquote>
381  <p>Returns a string containing the current Wave version formatted as <span class="string">0xvvrsbbbb</span> 
382    (this is a string representation of the equivalent hexadecimal number), where
383    <span class="literal">'vv'</span> is the version number, <span class="literal">'r'</span> 
384    the release number, <span class="literal">'s'</span> the subrelease number
385    and <span class="literal">'bbbb'</span> the build number. A possible return
386    value looks like <span class="literal">0x00910454</span>. The returned value
387    is the same as is inserted in the preprocessed token stream, when the predefined
388    macro <tt>__WAVE_VERSION__</tt> is expanded.</p>
389</blockquote>
390<p><b>get_version_str</b></p>
391<pre><span class="keyword">    </span><span class="keyword">static std::string</span> get_version_str(); </pre>
392<blockquote> 
393  <p>Returns a string containing the current Wave version formatted as <span class="string">&quot;v.rr.ss.bbbb&quot;</span>,
394    where <span class="literal">'v'</span> is the version number, <span class="literal">'rr'</span> 
395    the release number, <span class="literal">'ss'</span> the subrelease number
396    and <span class="literal">'bbbb'</span> the build number. A possible return
397    value looks like <span class="literal">&quot;0.9.1.454&quot;</span>. The returned
398    value is the same as it will be inserted in the preprocessed token stream, when the
399    predefined macro <tt>__WAVE_VERSION_STR__</tt> is expanded.</p>
400</blockquote>
401<h3>Control extended options</h3>
402<p><a name="language_support"></a>set_language<br>
403  get_language</p>
404<pre><span class="keyword">    void</span> set_language(<span class="keyword">language_support</span> language,
405        <span class="keyword">bool</span> reset_macros = <span class="keyword">true</span>);
406    <span class="keyword">language_support</span> get_language() <span class="keyword">const</span>;</pre>
407<blockquote> 
408  <p>This functions allows to specify the language mode, in which the <tt>Wave</tt> 
409    library should work. The possible language modes are defined by the enumerated
410    type <tt>language_support</tt>:</p>
411  <pre>    <span class="keyword">enum</span> language_support {
412    <span class="comment">// support flags for C++98</span>
413        support_normal = 0x01,
414        support_cpp = support_normal,
415   
416    <span class="comment">// support flags for C99</span>
417        support_option_long_long = 0x02,
418        support_option_variadics = 0x04,
419        support_c99 = support_option_variadics |
420                      support_option_long_long |
421                      0x08,
422
423<span class="comment">    // the mask for the main language settings</span>
424        support_option_mask = 0xFF00,<br>
425<span class="comment">    // additional fine tuning of the general behavior</span>
426        support_option_preserve_comments = 0x0100,
427        support_option_no_character_validation = 0x0200,
428        support_option_convert_trigraphs = 0x0400,
429        support_option_single_line = 0x0800,
430        support_option_prefer_pp_numbers = 0x1000,
431        support_option_emit_line_directives = 0x2000,
432        support_option_include_guard_detection = 0x4000
433    };</pre>
434  <p>When used with <tt>support_option_variadics</tt> the support for variadics, placemarkers
435    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>
436  <p>The <tt>support_c99</tt> switches on the C99 language support, which enables variadics, placemarkers, the <tt>operator&nbsp;_Pragma</tt> and long long suffixes by default. Additionally it disables the C++ specific tokens such as <tt>'-&gt;*'</tt>, <tt>'.*'</tt>, <tt>'::'</tt> etc. </p>
437  <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>
438  <ul>
439    <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>
440    <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>
441    <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>
442    <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>
443    <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>
444    <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>
445    <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>
446  </ul>
447  <blockquote>
448    <p>During this process the library will recognize two forms of include guards:</p>
449    <pre>    <span class="preprocessor">#ifndef</span> INCLUDE_GUARD_MACRO
450    <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO
451    ...
452    <span class="preprocessor">#endif</span>
453
454  or
455
456    <span class="preprocessor">#if</span> !defined(INCLUDE_GUARD_MACRO)
457    <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO
458    ...
459    <span class="preprocessor">#endif</span></pre>
460    <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
461      '#' 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>
462    <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>
463  </blockquote>
464  <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>
465</blockquote>
466<p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br>
467  get_max_include_nesting_depth</p>
468<pre><span class="keyword">    void</span> set_max_include_nesting_depth(size_t new_depth);
469    size_t get_max_include_nesting_depth() <span class="keyword">const</span>;</pre>
470<blockquote> 
471  <p>This functions allow to set or to get the maximal possible include file nesting
472    depth supported by the <tt>Wave</tt> library. The initial value for this is
473    determined by the preprocessing constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt> 
474    (see <a href="compiletime_config.html">here</a>).</p>
475</blockquote>
476<table border="0">
477  <tr> 
478    <td width="10"></td>
479    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
480    <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
481    <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td>
482  </tr>
483</table>
484<hr size="1">
485<p class="copyright">Copyright &copy; 2003-2007 Hartmut Kaiser<br>
486  <br>
487  <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>
488<span class="updated"></span>
489<p class="copyright"><span class="updated">Last updated:
490  <!-- #BeginDate format:fcAm1m -->Tuesday, March 20, 2007  14:04<!-- #EndDate -->
491  </span>
492</p>
493<p>&nbsp;</p>
494</body>
495</html>
Note: See TracBrowser for help on using the repository browser.