Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/wave/doc/class_reference_ctxpolicy.html @ 12

Last change on this file since 12 was 12, checked in by landauf, 17 years ago

added boost
File size: 19.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<title>The Context Policy</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<link href="theme/style.css" rel="stylesheet" type="text/css">
7</head>
8
9<body>
10<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
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
14      Context Policy</font></b></font></td>
15    <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
16  </tr>
17</table>
18<br>
19<table border="0">
20  <tr> 
21    <td width="10"></td>
22    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
23    <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
24    <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
25  </tr>
26</table>
27<blockquote> 
28  <p><a href="class_reference_ctxpolicy.html#introduction">Introduction</a><br>
29    <a href="class_reference_ctxpolicy.html#header_synopsis">Header 'wave/preprocessing_hooks.hpp'
30    synopsis</a><br>
31    <a href="class_reference_ctxpolicy.html#member_functions">Member functions</a></p>
32</blockquote>
33<h2><b><a name="introduction"></a>Introduction</b></h2>
34<p>The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever</p>
35<ul>
36  <li>a macro get's defined or undefind, </li>
37  <li>a macro is expanded or rescanned,</li>
38  <li>an include file is opened or left, </li>
39  <li> a pragma of the form <tt>'wave option[(value)]'</tt> is recognised. </li>
40</ul>
41<p>This policy type is used as a template parameter to the <a href="class_reference_context.html"><tt>wave::context&lt;&gt;</tt></a> 
42  object, where the default policy provides empty hooks functions only.</p>
43<h2><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/viewcvs.py/boost/boost/boost/wave/preprocessing_hooks.hpp?view=markup">wave/preprocessing_hooks.hpp</a> 
44  synopsis</h2>
45<pre>
46<span class="keyword">namespace</span> boost {
47<span class="keyword">namespace</span> wave {
48<span class="keyword">namespace</span> context_policies {
49 
50    <span class="keyword">struct</span> default_preprocessing_hooks {
51
52        <span class="comment">// general control function</span>
53        template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
54        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanding_function_like_macro">expanding_function_like_macro</a>(TokenT <span class="keyword">const</span> &amp;macrodef,
55            <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args,
56            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall,
57            <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments);
58 
59        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
60        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanding_object_like_macro">expanding_object_like_macro</a>(TokenT <span class="keyword">const</span> &amp;macro,
61            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
62 
63        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
64        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">expanded_macro</a>(ContainerT <span class="keyword">const</span> &amp;result);
65 
66        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
67        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">rescanned_macro</a>(ContainerT <span class="keyword">const</span> &amp;result);
68
69        <span class="comment">// include file tracing functions</span>
70        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#opened_include_file">found_include_directive</a>(std::string <span class="keyword">const</span> &amp;filename,
71            <span class="keyword">bool</span> include_next);
72
73        <span class="keyword">void </span><a href="class_reference_ctxpolicy.html#opened_include_file">opened_include_file</a>(std::string <span class="keyword">const</span> &amp;relname,
74            std::string const&amp; absname,
75            std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
76
77        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#returning_from_include_file">returning_from_include_file</a>();
78
79        <span class="comment">// interpretation of #pragma's of the form </span>
80        <span class="comment">// 'wave option[(value)]'</span>
81        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT&gt;
82                bool <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending,
83            <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option,
84            ContainerT <span class="keyword">const</span> &amp;values,
85            <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;pragma_token);
86
87        <span class="comment">// macro definition hooks</span>
88        <span class="keyword">template</span> &lt;
89            <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT
90        &gt;
91        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">bool</span> is_functionlike,
92            ParametersT <span class="keyword">const</span> &amp;parameters, DefinitionT <span class="keyword">const</span> &amp;definition,
93            <span class="keyword">bool</span> is_predefined);
94
95        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
96        <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(TokenT<span class="keyword">const</span> &amp;name);
97    };
98
99}}}   <span class="comment">// namespace boost::wave::context_policies</span></pre>
100<h2><a name="member_functions"></a>Member functions</h2>
101<h3>Macro expansion tracking functions</h3>
102<p><a name="expanding_function_like_macro"></a><b>expanding_function_like_macro</b></p>
103<pre><span class="keyword">    template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
104    <span class="keyword">void</span> expanding_function_like_macro(TokenT <span class="keyword">const</span> &amp;macrodef,
105        <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args,
106        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall,
107        <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments);</pre>
108<blockquote> 
109  <p>The function <tt>expanding_function_like_macro</tt> is called, whenever a
110    function-like macro is to be expanded, i.e. <i>before</i> the actual expansion
111    starts.</p>
112  <p>The <tt>macroname</tt> parameter marks the position where the macro to expand
113    is defined. It contains the token which identifies the macro name used inside
114    the corresponding macro definition.</p>
115  <p>The <tt>formal_args</tt> parameter holds the formal arguments used during
116    the definition of the macro. </p>
117  <p>The <tt>definition</tt> parameter holds the macro definition for the macro
118    to trace. This is a standard STL container which holds the token sequence
119    identified during the macro definition as the macro replacement list.</p>
120  <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked.
121    It contains the token, which identifies the macro call inside the preprocessed
122    input stream. </p>
123  <p>The <tt>arguments</tt> parameter holds the macro arguments used during the
124    invocation of the macro. This is a vector of standard STL containers which
125    contain the token sequences identified at the position of the macro call as
126    the arguments to be used during the macro expansion. </p>
127</blockquote>
128<p><a name="expanding_object_like_macro"></a><b>expanding_object_like_macro</b></p>
129<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
130    <span class="keyword">void</span> expanding_object_like_macro(TokenT <span class="keyword">const</span> &amp;macro,
131        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
132</pre>
133<blockquote> 
134  <p>The function <tt>expanding_object_like_macro</tt> is called, whenever a object-like
135    macro is to be expanded, i.e. <i>before</i> the actual expansion starts.</p>
136  <p>The <tt>macroname</tt> parameter marks the position where the macro to expand
137    is defined. It contains the token which identifies the macro name used inside
138    the corresponding macro definition.</p>
139  <p> The <tt>definition</tt> parameter holds the macro definition for the macro
140    to trace. This is a standard STL container which holds the token sequence
141    identified during the macro definition as the macro replacement list.</p>
142  <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked.
143    It contains the token which identifies the macro call inside the preprocessed
144    input stream. </p>
145</blockquote>
146<p><a name="expanded_macro"></a><b>expanded_macro</b></p>
147<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
148    <span class="keyword">void</span> expanded_macro(ContainerT <span class="keyword">const</span> &amp;result);
149</pre>
150<blockquote> 
151  <p>The function <tt>expanded_macro</tt> is called whenever the expansion of
152    a macro is finished, the replacement list is completely scanned and the identified
153    macros herein are replaced by its corresponding expansion results, but <i>before</i> 
154    the rescanning process starts.</p>
155  <p>The parameter <tt>result</tt> contains the the result of the macro expansion
156    so far. This is a standard STL container containing the generated token sequence.</p>
157</blockquote>
158<p><a name="rescanned_macro"></a><b>rescanned_macro</b></p>
159<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
160    <span class="keyword">void</span> rescanned_macro(ContainerT <span class="keyword">const</span> &amp;result);
161</pre>
162<blockquote> 
163  <p>The function <tt>rescanned_macro</tt> is called whenever the rescanning
164    of a macro is finished, i.e. the macro expansion is complete.</p>
165  <p>The parameter <tt>result</tt> contains the the result of the whole macro
166    expansion. This is a standard STL container containing the generated token
167    sequence.</p>
168</blockquote>
169<h3>Include file tracing functions</h3>
170<p><a name="opened_include_file" id="found_include_directive"></a><strong>found_include_directive</strong></p>
171<pre>    <span class="keyword">void</span> found_include_directive(std::string <span class="keyword">const</span> &amp;filename,
172        <span class="keyword">bool</span> include_next);
173</pre>
174<blockquote>
175  <p>The function <tt>found_include_directive</tt> is called whenever whenever a #include directive was located..</p>
176  <p>The parameter <tt>filename</tt> contains the (expanded) file name found after
177    the <span class="preprocessor">#include</span> directive. This has the format <tt>&lt;file&gt;</tt>, <tt>&quot;file&quot;</tt> or
178    <tt>file</tt>.
179    The formats <tt>&lt;file&gt;</tt> or <tt>&quot;file&quot;</tt> are used for <span class="preprocessor">#include</span> directives found
180    in the preprocessed token stream, the format <tt>file</tt> is used for files
181  specified through the --force_include command line argument.</p>
182  <p>The parameter <tt>include_next</tt> is set to true if the found directive was
183    a <span class="preprocessor">#include_next</span> directive and the <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt>    preprocessing constant was defined to something != 0.<br>
184  </p>
185</blockquote>
186<p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p>
187<pre>    <span class="keyword">void</span> opened_include_file(std::string <span class="keyword">const</span> &amp;rel_filename,
188        std::string <span class="keyword">const</span> &amp;abs_filename,
189        std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
190</pre>
191<blockquote> 
192  <p>The function <tt>opened_include_file</tt> is called whenever a file referred
193    by an <span class="preprocessor">#include</span> directive was successfully located and opened.</p>
194  <p>The parameter <tt>rel_filename</tt> contains the (normalised) probably relative file system path of the opened file. The concrete format of this file name depends on the format of the include search path given to the library beforehand.</p>
195  <p>The parameter <tt>abs_filename</tt> contains the (normalised) full file system path of the
196      opened file.</p>
197  <p>The <tt>include_depth</tt> parameter contains the current include file depth.
198  </p>
199  <p>The <tt>is_system_include</tt> parameter denotes, if the given file was found
200    as a result of a <tt>#include&nbsp;&lt;...&gt;</tt> directive.</p>
201</blockquote>
202<p><a name="returning_from_include_file" id="returning_from_include_file"></a><strong>returning_from_include_file</strong></p>
203<pre>    <span class="keyword">void</span> returning_from_include_file();
204</pre>
205<blockquote> 
206  <p>The function <tt>returning_from_include_file</tt> is called whenever an
207    included file is about to be closed after it's processing is complete.</p>
208</blockquote>
209<h3>Interpretation of #pragma's</h3>
210<p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p>
211<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> Context, <span class="keyword">typename</span> ContainerT&gt;
212    bool <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &amp;ctx, ContainerT &amp;pending,
213        <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &amp;option,
214        ContainerT <span class="keyword">const</span> &amp;values,
215        <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &amp;pragma_token);
216</pre>
217<blockquote> 
218  <p>The function <tt>interpret_pragma</tt> is called whenever an unrecognized
219    <tt>#pragma&nbsp;wave&nbsp;...</tt> or operator <tt>_Pragma(&quot;wave&nbsp;...&quot;)</tt> 
220    is found in the input stream.</p>
221  <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p>
222  <p>The <tt>pending</tt> parameter may be used to push tokens back into the input
223    stream which are to be used as the replacement text for the whole <tt>#pragma&nbsp;wave()</tt> 
224    directive. If this sequence is left empty, no replacement takes place, i.e.
225    the interpreted directive is removed from the generated token stream.</p>
226  <p>The <tt>option</tt> parameter contains the name of the interpreted pragma.</p>
227  <p>The <tt>values</tt> parameter holds the value of the parameter provided to
228    the pragma operator.</p>
229  <p>The <tt>pragma_token</tt> parameter contains the actual #pragma token which
230    may be used for extraction of the location information for some error output.</p>
231  <p>If the return value is 'false', the whole #pragma directive is interpreted
232    as unknown and a corresponding error message is issued. A return value of
233    'true' signs a successful interpretation of the given #pragma.<br>
234  </p>
235</blockquote>
236<h3>Macro definition </h3>
237<p><strong><a name="defined_macro" id="defined_macro"></a>defined_macro</strong></p>
238<pre>    <span class="keyword">template</span> &lt;
239        <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT
240    &gt;
241    <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(TokenT <span class="keyword">const</span> &amp;name, <span class="keyword">bool</span> is_functionlike,
242        ParametersT <span class="keyword">const</span> &amp;parameters, DefinitionT <span class="keyword">const</span> &amp;definition,
243        <span class="keyword">bool</span> is_predefined);
244</pre>
245<blockquote>  <p>The function <tt>defined_macro</tt> is called whenever a macro was defined successfully.</p>
246  <p>The parameter <tt>name</tt> is a reference to the token holding the macro name.</p>
247  <p>The parameter <tt>is_functionlike</tt> is set to true whenever the newly
248    defined macro is defined as a function like macro.</p>
249  <p>The parameter <tt>parameters</tt> holds the parameter tokens for the macro
250      definition. If the macro has no parameters or if it is a object like
251  macro, then this container is empty.</p>
252  <p>The parameter <tt>definition</tt> contains the token sequence given as the
253  replacement sequence (definition part) of the newly defined macro.</p>
254  <p>The parameter <tt>is_predefined</tt> is set to true for all macros predefined
255      during the initialisation pahase of the library.<br>
256  </p>
257</blockquote>
258<p><strong><a name="undefined_macro" id="undefined_macro"></a>undefined_macro</strong></p>
259<pre>    <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT&gt;
260    <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(TokenT<span class="keyword">const</span> &amp;name);
261</pre>
262<blockquote>
263  <p>The function <tt>undefined_macro</tt> is called whenever a macro definition
264    was removed successfully.</p>
265  <p>The parameter <tt>name</tt> holds the token of the macro which definition was removed.<br>
266  </p>
267</blockquote>
268<table border="0">
269  <tr> 
270    <td width="10"></td>
271    <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
272    <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
273    <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
274  </tr>
275</table>
276<hr size="1">
277<p class="copyright">Copyright &copy; 2003-2005 Hartmut Kaiser<br>
278  <br>
279<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>
280<span class="updated"></span>
281<p class="copyright"><span class="updated">Last updated:
282  <!-- #BeginDate format:fcAm1m -->Sunday, May 15, 2005  12:23<!-- #EndDate -->
283</span></p>
284</body>
285</html>
Note: See TracBrowser for help on using the repository browser.