| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>The Context Policy</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link href="theme/style.css" rel="stylesheet" type="text/css"> |
| <style type="text/css"> |
| .style1 { |
| background-color: #EEEEEE; |
| } |
| </style> |
| </head> |
| <body> |
| <table background="theme/bkd2.gif" border="0" cellspacing="2" width="100%"> |
| <tbody> |
| <tr> |
| <td width="21"> </td> |
| <td width="885"><font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>The |
| Context Policy </b></font></td> |
| <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" align="right" border="0" height="68" width="93"></a></td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <table border="0"> |
| <tbody> |
| <tr> |
| <td width="10"></td> |
| <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
| <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td> |
| <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td> |
| </tr> |
| </tbody> |
| </table> |
| <blockquote> |
| <p><a href="class_reference_ctxpolicy.html#introduction">Introduction</a><br> |
| <a href="class_reference_ctxpolicy.html#header_synopsis">Header 'wave/preprocessing_hooks.hpp' |
| synopsis</a><br> |
| <a href="class_reference_ctxpolicy.html#member_functions">Member functions</a></p> |
| </blockquote> |
| <h2><b><a name="introduction"></a>Introduction</b></h2> |
| <p>Please note that the following description relates to the new |
| preprocessing hooks interface used by default starting with the Boost |
| V1.35.0 release. If you are interested in the older interface please |
| look <a href="class_ref_ctxpolicy_depr.html">here</a>. </p> |
| <p>The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever</p> |
| <ul> |
| <li>a preprocessor directive has been recognized, </li> |
| <li>a token is about to be returned from the preprocessor, </li> |
| <li>a macro get's defined or undefined, </li> |
| <li>a macro has been expanded or rescanned,</li> |
| <li>an include file has been opened or closed, </li> |
| <li>a conditional expression was evaluated,</li> |
| <li>a token has to be skipped because it is contained in a non-evaluated conditional block, </li> |
| <li> a pragma of the form <tt>'wave option[(value)]'</tt> has been recognized. </li> |
| </ul> |
| <p>This policy type is used as a template parameter to the <a href="class_reference_context.html"><tt>boost::wave::context<></tt></a> object, where the default policy provides empty hook functions only.</p> |
| <h2><a name="header_synopsis"></a>Header <a href="http://svn.boost.org/trac/boost/browser/trunk/boost/wave/preprocessing_hooks.hpp">wave/preprocessing_hooks.hpp</a> synopsis</h2> |
| <pre><span class="keyword">namespace</span> boost {<br><span class="keyword">namespace</span> wave {<br><span class="keyword">namespace</span> context_policies {<br> <br> <span class="keyword">struct</span> default_preprocessing_hooks {<br><br> <span class="comment">// general hook functions</span> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_directive">found_directive</a>(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const </span>&directive);<br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT><br> void <a href="class_reference_ctxpolicy.html#trow_exception">throw_exception</a>(ContextT <span class="keyword">const</span> &ctx, <br> ExceptionT <span class="keyword">const</span>& e);<br><br> <span class="comment">// test, whether a given token may be skipped</span><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#may_skip_whitespace">may_skip_whitespace</a> (ContextT <span class="keyword">const</span>& ctx,<br> TokenT &token, <span class="keyword">bool</span> &skipped_newline);<br> |
| <span class="comment">// Conditional compilation</span><span class="keyword"> |
| template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <br> <span class="keyword">typename</span> ContainerT<br> ><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#evaluated_conditional_expression">evaluated_conditional_expression</a>(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span>& directive, <br> ContainerT <span class="keyword">const</span>& expression, <span class="keyword">bool</span> expression_value);<br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#skipped_token">skipped_token</a>(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const</span>& token);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> TokenT <span class="keyword">const</span>& <a href="class_reference_ctxpolicy.html#generated_token">generated_token</a>(ContextT <span class="keyword">const</span> &ctx, <br> TokenT <span class="keyword">const</span>& token);<br><br> <span class="comment">// macro expansion tracing</span><span class="keyword"> |
| template</span> <<span class="keyword"> |
| typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT,<br> <span class="keyword">typename</span> IteratorT<br> ><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#expanding_function_like_macro">expanding_function_like_macro</a>(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macrodef, <br> <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall, <br> <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,<br> IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);<br> <br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#expanding_object_like_macro">expanding_object_like_macro</a>(<br> ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &macro, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);<br> <br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">expanded_macro</a>(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &result);<br> <br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#expanded_macro">rescanned_macro</a>(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &result);<br><br> |
| <span class="comment">// include file tracing functions</span> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#opened_include_file">found_include_directive</a>(ContextT <span class="keyword">const</span> &ctx, <br> std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next);<br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void </span><a href="class_reference_ctxpolicy.html#opened_include_file">opened_include_file</a>(ContextT <span class="keyword">const</span> &ctx, <br> std::string <span class="keyword">const</span> &relname, std::string <span class="keyword">const</span>& absname,<br> <span class="keyword">bool</span> is_system_include); <br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#returning_from_include_file">returning_from_include_file</a>(ContextT <span class="keyword">const</span> &ctx);<br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> <a href="#detected_include_guard">detected_include_guard</a>(ContextT <span class="keyword">const</span> &ctx, |
| std::string <span class="keyword">const</span>& filename, |
| std::string <span class="keyword">const</span>& include_guard);<br> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> <a href="#detected_pragma_once">detected_pragma_once</a>(ContextT <span class="keyword">const</span> &ctx, |
| TokenT <span class="keyword">const</span>& pragma_token, |
| std::string <span class="keyword">const</span>& filename);<br><br> |
| <span class="comment">// interpretation of #pragma's of the form </span> |
| <span class="comment">// 'wave option[(value)]'</span> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option, <br> ContainerT <span class="keyword">const</span> &values, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &pragma_token);<br><br> |
| <span class="comment">// macro definition hooks</span> |
| <span class="keyword">template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword"> |
| typename</span> ParametersT, <span class="keyword">typename</span> DefinitionT<br> ><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(ContextT <span class="keyword">const</span> &ctx, TokenT <span class="keyword">const</span> &name, <span class="keyword"> |
| bool</span> is_functionlike, ParametersT <span class="keyword">const</span> &parameters, <br> DefinitionT <span class="keyword">const</span> &definition, <span class="keyword">bool</span> is_predefined);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(ContextT <span class="keyword">const</span> &ctx, <br> TokenT<span class="keyword"> const</span> &name);<br><br> |
| <span class="comment">// #error and #warning directive hooks</span> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_warning_directive">found_warning_directive</a>(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &message);<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_error_directive">found_error_directive</a>(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &message);<br><br> <span class="comment">// #line directive hook</span> |
| <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#found_line_directive">found_line_directive</a>(ContextT <span class="keyword">const</span> &ctx, <br> ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,<br> std::string <span class="keyword">const</span>& filename);<br> };<br><br>}}} <span class="comment">// namespace boost::wave::context_policies</span></pre> |
| <h2><a name="member_functions"></a>Member functions</h2> |
| <h3>General hook functions </h3> |
| <p><a name="found_directive"></a><strong>found_directive</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> found_directive(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const </span>&directive); |
| </pre> |
| <blockquote> |
| <p>The function <tt>found_directive</tt> is called, whenever the preprocessor has detected one of the preprocessing directives (<span class="preprocessor">#define</span>, <span class="preprocessor">#undef</span>, <span class="preprocessor">#if</span>, <span class="preprocessor">#idef</span>, <span class="preprocessor">#ifndef</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#endif</span>, <span class="preprocessor">#error</span>, <span class="preprocessor">#include</span>, <span class="preprocessor">#pragma</span> or <span class="preprocessor">#warning</span>) .</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>directive</tt> refers to the token containing the detected preprocessing directive. </p> |
| <p>If the return value is <tt>true</tt>, the directive will be |
| skipped altogether, i.e. no preprocessing is done. The overall |
| directive is replaced by a single newline character. If the return |
| value is <tt>false</tt>, the directive is processed in the normal manner. </p> |
| </blockquote> |
| <p><a name="throw_exception"></a><strong>throw_exception</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ExceptionT><br> void throw_exception(ContextT <span class="keyword">const</span> &ctx, <br> ExceptionT <span class="keyword">const</span>& e);</pre> |
| <blockquote> |
| <p>he function <tt>throw_exception</tt> is called, whenever a preprocessing exception occurs .</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The parameter <tt>e</tt> is the exception object containing detailed error information. </p> |
| </blockquote> |
| <p><a name="may_skip_whitespace" id="may_skip"></a><strong>may_skipwhitespace</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">bool</span> may_skip_whitespace(ContextT <span class="keyword">const</span>& ctx, TokenT &token, <br> <span class="keyword">bool</span>& skipped_newline); |
| </pre> |
| <blockquote> |
| <p>The function <tt>may_skipwhitespace</tt> will be called by the library, whenever a token is about to be returned to the calling application. </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Wave V1.2.4 release. </p> |
| <p>The <tt>token</tt> parameter holds a reference to the current token. The policy is free to change this token if needed.</p> |
| <p>The <tt>skipped_newline</tt> parameter holds a reference to a |
| boolean value which should be set to true by the policy function |
| whenever a newline is going to be skipped. </p> |
| <p>If the return value is <tt>true</tt>, the given token is skipped and the preprocessing continues to the next token. If the return value is <tt>false</tt>, the given token is returned to the calling application. Caution has to be used, because by returning <span class="keyword">true</span> the policy function is able to force skipping even significant tokens not only whitespace. </p> |
| </blockquote> |
| <h3>Conditional compilation hook functions </h3> |
| <p><a name="evaluated_conditional_expression"></a><strong>evaluated_conditional_expression</strong></p> |
| <pre><span class="keyword"> template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT> |
| <span class="keyword"> bool</span> evaluated_conditional_expression(ContextT <span class="keyword">const</span>& ctx, <br> TokenT <span class="keyword">const</span>& directive, ContainerT <span class="keyword">const</span>& expression, <span class="keyword"><br> bool</span> expression_value); |
| </pre> |
| <blockquote> |
| <p>The function <tt>evaluated_conditional_expression</tt> is called, whenever the preprocessor has encountered a <span class="preprocessor">#if</span>, <span class="preprocessor">#elif</span>, <span class="preprocessor">#ifdef</span> or <span class="preprocessor">#ifndef</span> directive. This hook gets passed the non-expanded conditional |
| expression (as it was given in the analysed source file) and the result |
| of the evaluation of this expression in the current preprocessing |
| context.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The <tt>token</tt> parameter holds a reference to the evaluated directive token. </p> |
| <p>The parameter <tt>expression</tt> holds the non-expanded token sequence |
| comprising the evaluated expression.</p> |
| <p>The parameter <tt>expression_value</tt> contains the result of the evaluation of |
| the expression in the current preprocessing context. </p> |
| <p>The return value defines, whether the given expression has to be |
| evaluated again, allowing to decide which of the conditional branches |
| should be expanded. You need to return '<span class="keyword">true</span>' from this hook function to force the expression to be re-evaluated. Note, this was changed from a '<span class="keyword">void</span>' for the Boost V1.35.0 release. <br> |
| </p> |
| </blockquote> |
| <p><a name="skipped_token"></a><strong>skipped_token</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> skipped_token(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span>& token); |
| </pre> |
| <blockquote> |
| <p>The function <tt>skipped_token</tt> is called, whenever a token is about to be skipped due to a false preprocessor condition (code fragments to be |
| skipped inside the not evaluated conditional <span class="preprocessor">#if</span>/<span class="preprocessor">#else</span>/<span class="preprocessor">#endif</span> branches).</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>token</tt> refers to the token to be skipped.</p> |
| </blockquote> |
| <p><a name="generated_token"></a><strong>generated_token</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> TokenT <span class="keyword">const</span>& generated_token(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span>& token); |
| </pre> |
| <blockquote> |
| <p>The function <tt>generated_token</tt> is called, whenever a token is about to be returned from the library.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>token</tt> refers to the token about to be |
| returned from the library. This function may alter the token, but in |
| this case it must be implemented with a non-const reference for the |
| token parameter, allowing to modify the token in place.</p> |
| <p>The default behavior is to return the passed token reference unchanged to the caller.</p> |
| </blockquote> |
| <h3>Macro expansion tracking functions</h3> |
| <p><a name="expanding_function_like_macro"></a><b>expanding_function_like_macro</b></p> |
| <pre><span class="keyword"> template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> expanding_function_like_macro(<br> ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macrodef, <br> <span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall, <br> <span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments,<br> IteratorT <span class="keyword">const</span> &seqstart, Iterator <span class="keyword">const</span> &seqend);</pre> |
| <blockquote> |
| <p>The function <tt>expanding_function_like_macro</tt> is called, whenever a |
| function-like macro is to be expanded, i.e. <i>before</i> the actual expansion |
| starts.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The <tt>macroname</tt> parameter marks the position where the macro to expand |
| is defined. It contains the token which identifies the macro name used inside |
| the corresponding macro definition.</p> |
| <p>The <tt>formal_args</tt> parameter holds the formal arguments used during |
| the definition of the macro. </p> |
| <p>The <tt>definition</tt> parameter holds the macro definition for the macro |
| to trace. This is a standard STL container which holds the token sequence |
| identified during the macro definition as the macro replacement list.</p> |
| <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked. |
| It contains the token, which identifies the macro call inside the preprocessed |
| input stream. </p> |
| <p>The <tt>arguments</tt> parameter holds the macro arguments used during the |
| invocation of the macro. This is a vector of standard STL containers which |
| contain the token sequences identified at the position of the macro call as |
| the arguments to be used during the macro expansion. </p> |
| <p>The parameters <tt>seqstart</tt> and <tt>seqend</tt> point into the input token |
| stream allowing to access the whole token sequence comprising the macro |
| invocation (starting with the opening parenthesis and ending after the |
| closing one).</p> |
| <p>If the return value is <tt>true</tt>, the macro is not expanded, |
| i.e. the overall macro invocation sequence, including the parameters |
| are copied to the output without further processing . If the return |
| value is <tt>false</tt>, the macro is expanded as expected. <br> |
| </p> |
| </blockquote> |
| <p><a name="expanding_object_like_macro"></a><b>expanding_object_like_macro</b></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> expanding_object_like_macro(<br> ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &macro, <br> ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall); |
| </pre> |
| <blockquote> |
| <p>The function <tt>expanding_object_like_macro</tt> is called, whenever a object-like |
| macro is to be expanded, i.e. <i>before</i> the actual expansion starts.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The <tt>macroname</tt> parameter marks the position where the macro to expand |
| is defined. It contains the token which identifies the macro name used inside |
| the corresponding macro definition.</p> |
| <p> The <tt>definition</tt> parameter holds the macro definition for the macro |
| to trace. This is a standard STL container which holds the token sequence |
| identified during the macro definition as the macro replacement list.</p> |
| <p>The <tt>macrocall</tt> parameter marks the position where this macro is invoked. |
| It contains the token which identifies the macro call inside the preprocessed |
| input stream. </p> |
| <p>If the return value is <tt>true</tt>, the macro is not expanded, i.e. the macro symbol is copied to the output without further processing. If the return value is <tt>false</tt>, the macro is expanded as expected. <br> |
| </p> |
| </blockquote> |
| <p><a name="expanded_macro"></a><b>expanded_macro</b></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> expanded_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result); |
| </pre> |
| <blockquote> |
| <p>The function <tt>expanded_macro</tt> is called whenever the expansion of |
| a macro is finished, the replacement list is completely scanned and the identified |
| macros herein are replaced by its corresponding expansion results, but <i>before</i> the rescanning process starts.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>result</tt> contains the the result of the macro expansion |
| so far. This is a standard STL container containing the generated token sequence.</p> |
| </blockquote> |
| <p><a name="rescanned_macro"></a><b>rescanned_macro</b></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> rescanned_macro(ContextT <span class="keyword">const</span>& ctx, ContainerT <span class="keyword">const</span> &result); |
| </pre> |
| <blockquote> |
| <p>The function <tt>rescanned_macro</tt> is called whenever the rescanning |
| of a macro is finished, i.e. the macro expansion is complete.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>result</tt> contains the the result of the whole macro |
| expansion. This is a standard STL container containing the generated token |
| sequence.</p> |
| </blockquote> |
| <h3>Include file tracing functions</h3> |
| <p><a name="opened_include_file" id="found_include_directive"></a><strong>found_include_directive</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">bool</span> found_include_directive(ContextT <span class="keyword">const</span>& ctx, <br> std::string <span class="keyword">const</span> &filename, <span class="keyword">bool</span> include_next); |
| </pre> |
| <blockquote> |
| <p>The function <tt>found_include_directive</tt> is called whenever whenever a #include directive was located..</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>filename</tt> contains the (expanded) file name found after |
| the <span class="preprocessor">#include</span> directive. This has the format <tt><file></tt>, <tt>"file"</tt> or <tt>file</tt>. |
| The formats <tt><file></tt> or <tt>"file"</tt> are used for <span class="preprocessor">#include</span> directives found |
| in the preprocessed token stream, the format <tt>file</tt> is used for files |
| specified through the --force_include command line argument.</p> |
| <p>The parameter <tt>include_next</tt> is set to true if the found directive was |
| a <span class="preprocessor">#include_next</span> directive and the <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt> preprocessing constant was defined to something != 0.</p> |
| <p>If the return value is <tt>true</tt>, the include directive is not |
| executed, i.e. the file to include is not loaded nor processed. The |
| overall directive is replaced by a single newline character. If the |
| return value is <tt>false</tt>, the directive is executed in a normal manner. <br> |
| </p> |
| </blockquote> |
| <p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> opened_include_file(ContextT <span class="keyword">const</span>& ctx, <br> std::string <span class="keyword">const</span> &rel_filename, std::string <span class="keyword">const</span> &abs_filename, <br> <span class="keyword">bool</span> is_system_include); |
| </pre> |
| <blockquote> |
| <p>The function <tt>opened_include_file</tt> is called whenever a file referred |
| by an <span class="preprocessor">#include</span> directive was successfully located and opened.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>rel_filename</tt> contains the (normalised) |
| probably relative file system path of the opened file. The concrete |
| format of this file name depends on the format of the include search |
| path given to the library beforehand.</p> |
| <p>The parameter <tt>abs_filename</tt> contains the (normalised) full file system path of the |
| opened file.</p> |
| <p>The <tt>is_system_include</tt> parameter denotes, if the given file was found |
| as a result of a <tt>#include <...></tt> directive.</p> |
| </blockquote> |
| <p><a name="returning_from_include_file" id="returning_from_include_file"></a><strong>returning_from_include_file</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> returning_from_include_file(ContextT <span class="keyword">const</span>& ctx); |
| </pre> |
| <blockquote> |
| <p>The function <tt>returning_from_include_file</tt> is called whenever an |
| included file is about to be closed after it's processing is complete.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| </blockquote> |
| <p><a name="detected_include_guard" id="detected_include_guard"></a><strong>detected_include_guard</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT><br> <span class="keyword">void</span> detected_include_guard(ContextT <span class="keyword">const</span>& ctx, |
| std::string <span class="keyword">const</span>& filename, |
| std::string <span class="keyword">const</span>& include_guard); |
| </pre> |
| <blockquote> |
| <p>The function <tt>detected_include_guard</tt> is called whenever a<span lang="de">n</span> |
| include file is about to be added to the list of #pragma once headers as the |
| result of a detected include guard scheme. That means this header file will |
| not be opened and parsed again even if it is specified in a later |
| <span class="preprocessor">#include</span> directive. </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> |
| used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The parameter <tt>filename</tt> contains the file system path of the opened file |
| (this is relative to the directory of the currently processed file or a |
| absolute path depending on the paths given as the include search paths).</p> |
| <p>The parameter <tt>include_guard</tt> contains the name of the detected include guard.<br> </p> |
| </blockquote> |
| <p><a name="detected_pragma_once" id="detected_pragma_once"></a><strong>detected_pragma_once</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename </span>TokenT><br> <span class="keyword">void</span> detected_<span lang="de">p<span class="style1">ragma<span lang="en-us">_</span>once</span></span>(ContextT <span class="keyword">const</span>& ctx, |
| <span lang="de"> TokenT <span class="keyword">const</span>& pragma_token,</span> |
| std::string <span class="keyword">const</span>& filename);</pre> |
| <blockquote> |
| <p>The function <tt>detected_pragma_once</tt> is called whenever either a<span lang="de">n</span> |
| include file is about to be added to the list of #pragma once headers as the |
| result of a detected <span lang="de"><span class="preprocessor">#pragma once</span> |
| directive</span>. That means this header file will not be opened and parsed |
| again even if it is specified in a later <span class="preprocessor">#include</span> |
| directive. </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> |
| used during instantiation of the preprocessing iterators by the user. </p> |
| <p><span lang="de">The parameter pragma_token refers to the token "#pragma" |
| triggering this preprocessing hook.</span></p> |
| <p>The parameter <tt>filename</tt> contains the file system path of the opened file |
| (this is relative to the directory of the currently processed file or a |
| absolute path depending on the paths given as the include search paths).</p> |
| </blockquote> |
| <h3>Interpretation of #pragma's</h3> |
| <p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> bool <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a>(ContextT <span class="keyword">const</span> &ctx, ContainerT &pending, <br> <span class="keyword">typename</span> ContextT::token_type <span class="keyword">const</span> &option, <br> ContainerT <span class="keyword">const</span> &values, <br> <span class="keyword">typename</span> ContextT::token_type<span class="keyword"> const</span> &pragma_token);<br> |
| </pre> |
| <blockquote> |
| <p>The function <tt>interpret_pragma</tt> is called whenever an unrecognized <tt>#pragma wave ...</tt> or operator <tt>_Pragma("wave ...")</tt> is found in the input stream.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The <tt>pending</tt> parameter may be used to push tokens back into the input |
| stream which are to be used as the replacement text for the whole <tt>#pragma wave()</tt> directive. If this sequence is left empty, no replacement takes place, i.e. |
| the interpreted directive is removed from the generated token stream.</p> |
| <p>The <tt>option</tt> parameter contains the name of the interpreted pragma.</p> |
| <p>The <tt>values</tt> parameter holds the value of the parameter provided to |
| the pragma operator.</p> |
| <p>The <tt>pragma_token</tt> parameter contains the actual #pragma token which |
| may be used for extraction of the location information for some error output.</p> |
| <p>If the return value is 'false', the whole #pragma directive is interpreted |
| as unknown and a corresponding error message is issued. A return value of |
| 'true' signs a successful interpretation of the given #pragma.<br> |
| </p> |
| </blockquote> |
| <h3>Macro definition </h3> |
| <p><strong><a name="defined_macro" id="defined_macro"></a>defined_macro</strong></p> |
| <pre> <span class="keyword">template</span> <<br> <span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ParametersT, <span class="keyword"> |
| typename</span> DefinitionT<br> ><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#defined_macro">defined_macro</a>(ContextT <span class="keyword">const</span>& ctx, <br> TokenT <span class="keyword">const</span> &name, <span class="keyword">bool</span> is_functionlike,<br> ParametersT <span class="keyword">const</span> &parameters, DefinitionT <span class="keyword">const</span> &definition,<br> <span class="keyword">bool</span> is_predefined);<br> |
| </pre> |
| <blockquote> |
| <p>The function <tt>defined_macro</tt> is called whenever a macro was defined successfully.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>name</tt> is a reference to the token holding the macro name.</p> |
| <p>The parameter <tt>is_functionlike</tt> is set to true whenever the newly |
| defined macro is defined as a function like macro.</p> |
| <p>The parameter <tt>parameters</tt> holds the parameter tokens for the macro |
| definition. If the macro has no parameters or if it is a object like |
| macro, then this container is empty.</p> |
| <p>The parameter <tt>definition</tt> contains the token sequence given as the |
| replacement sequence (definition part) of the newly defined macro.</p> |
| <p>The parameter <tt>is_predefined</tt> is set to true for all macros predefined |
| during the initialisation pahase of the library.<br> |
| </p> |
| </blockquote> |
| <p><strong><a name="undefined_macro" id="undefined_macro"></a>undefined_macro</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> TokenT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#undefined_macro">undefined_macro</a>(ContextT <span class="keyword">const</span>& ctx, TokenT <span class="keyword">const</span> &name);<br> |
| </pre> |
| <blockquote> |
| <p>The function <tt>undefined_macro</tt> is called whenever a macro definition |
| was removed successfully.</p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. |
| Note, this parameter was added for the Boost V1.35.0 release. </p> |
| <p>The parameter <tt>name</tt> holds the token of the macro which definition was removed.<br> |
| </p> |
| </blockquote> |
| <p><strong><a name="found_warning_directive" id="found_warning_directive"></a>found_warning_drective</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_warning_directive">found_warning_directive</a>(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &message);<br> |
| </pre> |
| <blockquote> |
| <p>The function <tt>found_warning_directive </tt> is called whenever a <span class="preprocessor">#warning </span>directive |
| has been encountered. Note, this function was added for the Boost |
| V1.35.0 release. This function will be called only if the <tt>BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE</tt> compile time constant was defined to something not equal to zero (see the <a href="compiletime_config.html">Compile Time Configuration</a> for more information). </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#warning</span> directive.</p> |
| <p>If the return value is <tt>false</tt>, the library throws a preprocessor |
| exception of the type <code>warning_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#warning</span> directive has been found and the overall directive is replaced by a single newline. </p> |
| </blockquote> |
| <p><strong><a name="found_error_directive" id="found_error_directive"></a>found_error_drective</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">bool</span> <a href="class_reference_ctxpolicy.html#found_error_directive">found_error_directive</a>(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &message);<br> |
| </pre> |
| <blockquote> |
| <p>The function <tt>found_error_directive </tt> is called whenever a <span class="preprocessor">#error </span>directive has been encountered. Note, this function was added for the Boost V1.35.0 release. </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The parameter <tt>message</tt> references the argument token sequence of the encountered <span class="preprocessor">#error</span> directive.</p> |
| <p>If the return value is <tt>false</tt>, the library throws a preprocessor |
| exception of the type <code>error_directive</code> (normal execution continues), if the return value is <tt>true</tt> the execution continues as if no <span class="preprocessor">#error</span> directive has been found and the overall directive is replaced by a single newline. </p> |
| </blockquote> |
| <p><strong><a name="found_line_directive" id="found_line_directive"></a>found_line_drective</strong></p> |
| <pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContextT, <span class="keyword">typename</span> ContainerT><br> <span class="keyword">void</span> <a href="class_reference_ctxpolicy.html#found_error_directive"><strong>found_line_drective</strong></a>(ContextT <span class="keyword">const</span>& ctx, <br> ContainerT <span class="keyword">const</span> &arguments, <span class="keyword">unsigned int</span> line,<br> std::string <span class="keyword">const</span>& filename); |
| </pre> |
| <blockquote> |
| <p>The function <tt>found_line_directive </tt> is called whenever a <span class="preprocessor">#line </span>directive has been encountered. Note, this function was added for the Boost V1.35.0 release. </p> |
| <p>The <tt>ctx</tt> parameter provides a reference to the <tt>context_type</tt> used during instantiation of the preprocessing iterators by the user. </p> |
| <p>The parameter <tt>arguments</tt> references the argument token sequence of the encountered <span class="preprocessor">#line</span> directive.</p> |
| <p>The parameter <tt>line</tt> contains the recognized line number from the <span class="preprocessor">#line</span> directive.</p> |
| <p>The parameter <tt>filename</tt> references the recognized file name from the <span class="preprocessor">#line</span> directive (if there was one given).<br> |
| </p> |
| </blockquote> |
| <table border="0"> |
| <tbody> |
| <tr> |
| <td width="10"></td> |
| <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
| <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td> |
| <td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td> |
| </tr> |
| </tbody> |
| </table> |
| <hr size="1"> |
| <p class="copyright">Copyright © 2003-2010 Hartmut Kaiser<br> |
| <br> |
| <font size="2">Distributed under the Boost Software License, Version |
| 1.0. (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt) </font> </p> |
| <p class="copyright"><span class="updated">Last updated: |
| <!-- #BeginDate format:fcAm1m -->Thursday, September 1<span lang="de">8</span>, 2010 |
| <span lang="de">09</span>:<span lang="de">10</span><!-- #EndDate --> |
| </span></p> |
| </body> |
| </html> |
