123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435 |
- <!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-2011 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>
|