mirror of
https://github.com/boostorg/wave.git
synced 2026-01-19 04:42:16 +00:00
Additional documentation (#121)
* Add documentation for three undocumented hooks Those are found_unknown_directive, emit_line_directive, and locate_include_file Also tweak formatting, fix typos. * Add documentation for five samples * Add links from samples docs to the hooks they use
This commit is contained in:
Jeff Trull
GitHub
@@ -45,27 +45,38 @@
|
||||
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 preprocessor directive has been recognized (or <b>not</b> recognized), </li>
|
||||
<li>a token is about to be returned from the preprocessor, </li>
|
||||
<li>a macro gets defined or undefined, </li>
|
||||
<li>a macro has been expanded or rescanned,</li>
|
||||
<li>a <span class="preprocessor">#line</span> directive is emitted,</li>
|
||||
<li>an include file is searched for in the filesystem,</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>
|
||||
<li>a token has to be skipped because it is contained in a non-evaluated conditional block, or</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> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>>
|
||||
<span class="type">bool</span> <a href="class_reference_ctxpolicy.html#found_unknown_directive">found_unknown_directive</a>(<span class="type">ContextT</span> <span class="keyword">const</span>& <span class="variable-name">ctx</span>,
|
||||
<span class="type">ContainerT</span> <span class="keyword">const</span>& <span class="variable-name">line</span>, <span class="type">ContainerT</span>& <span class="variable-name">pending</span>);
|
||||
</span>
|
||||
<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">
|
||||
<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><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> <span class="type">ContextT</span>>
|
||||
<span class="type">bool</span> <a href="class_reference_ctxpolicy.html#locate_include_file">locate_include_file</a>(<span class="type">ContextT</span>& <span class="variable-name">ctx</span>, <span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">file_path</span>,
|
||||
<span class="type">bool</span> <span class="variable-name">is_system</span>, <span class="type">char</span> <span class="keyword">const</span> *<span class="variable-name">current_name</span>,
|
||||
<span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">dir_path</span>, <span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">native_name</span>);<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,
|
||||
@@ -82,8 +93,13 @@
|
||||
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>
|
||||
<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 hooks</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>
|
||||
<span class="keyword">template</span> <<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>>
|
||||
<span class="type">bool</span> <a href="class_reference_ctxpolicy.html#emit_line_directive">emit_line_directive</a>(<span class="type">ContextT</span> <span class="keyword">const</span>& <span class="variable-name">ctx</span>, <span class="type">ContainerT</span> &<span class="variable-name">pending</span>,
|
||||
<span class="keyword">typename</span> <span class="constant">ContextT</span>::<span class="type">token_type</span> <span class="keyword">const</span>& <span class="variable-name">act_token</span>);
|
||||
|
||||
};<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>
|
||||
@@ -99,18 +115,33 @@
|
||||
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>
|
||||
|
||||
<p><a name="found_unknown_directive"></a><strong>found_unknown_directive</strong></p>
|
||||
<pre>
|
||||
<span class="keyword">template</span> <<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>>
|
||||
<span class="type">bool</span> <span class="function-name">found_unknown_directive</span>(<span class="type">ContextT</span> <span class="keyword">const</span>& <span class="variable-name">ctx</span>,
|
||||
<span class="type">ContainerT</span> <span class="keyword">const</span>& <span class="variable-name">line</span>, <span class="type">ContainerT</span>& <span class="variable-name">pending</span>);
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p>he function <tt>throw_exception</tt> is called, whenever a preprocessing exception occurs .</p>
|
||||
<p>The function <tt>found_unknown_directive</tt> is called, whenever an unknown preprocessor directive was encountered.</p>
|
||||
<p>The parameter <tt>ctx</tt> is a reference to the context object used for instantiating the preprocessing iterators by the user.</p>
|
||||
<p>The parameter <tt>line</tt> holds the tokens of the entire source line containing the unknown directive.</p>
|
||||
<p>The parameter <tt>pending</tt> may be used to push tokens back into the input stream, which are to be used as the replacement text for the whole line containing the unknown directive.</p>
|
||||
<p>The return value defines whether the given expression has been properly interpreted by the hook function or not. If this function returns <tt>false</tt>, the library will raise an <tt>ill_formed_directive</tt> exception. Otherwise the tokens pushed back into <tt>pending</tt> are passed on to the user program.</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>The 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>
|
||||
<p><a name="may_skip_whitespace" id="may_skip"></a><strong>may_skip_whitespace</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 function <tt>may_skip_whitespace</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>
|
||||
@@ -263,6 +294,47 @@
|
||||
return value is <tt>false</tt>, the directive is executed in a normal manner. <br>
|
||||
</p>
|
||||
</blockquote>
|
||||
<p><a name="locate_include_file" id="locate_include_file"></a><strong>locate_include_file</strong></p>
|
||||
<pre>
|
||||
<span class="keyword">template</span> <<span class="keyword">typename</span> <span class="type">ContextT</span>>
|
||||
<span class="type">bool</span> <span class="function-name">locate_include_file</span>(<span class="type">ContextT</span>& <span class="variable-name">ctx</span>, <span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">file_path</span>,
|
||||
<span class="type">bool</span> <span class="variable-name">is_system</span>, <span class="type">char</span> <span class="keyword">const</span> *<span class="variable-name">current_name</span>, <span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">dir_path</span>,
|
||||
<span class="constant">std</span>::<span class="type">string</span> &<span class="variable-name">native_name</span>)
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p>The function <tt>locate_include_file</tt> is called, whenever a <span class="preprocessor">#include</span>
|
||||
directive was encountered. It is supposed to locate the given file and
|
||||
should return the full file name of the located file. This file name
|
||||
is expected to uniquely identify the referenced file.</p>
|
||||
|
||||
<p>The parameter <tt>ctx</tt> is a reference to the context object used for
|
||||
instantiating the preprocessing iterators by the user.</p>
|
||||
|
||||
<p>The parameter <tt>file_path</tt> contains the (expanded) file name found after
|
||||
the <tt>#include</tt> directive. This parameter holds the string as it is
|
||||
specified in the <span class="preprocessor">#include</span> directive, i.e. <tt><file></tt> or <tt>"file"</tt> will result
|
||||
in a parameter value 'file'.</p>
|
||||
|
||||
<p>The parameter <tt>is_system</tt> is set to <tt>true</tt> if this call happens as a
|
||||
result of a <span class="preprocessor">#include <file></span> directive, it is <tt>false</tt> otherwise, i.e.
|
||||
for <span class="preprocessor">#include "file"</span> directives.</p>
|
||||
|
||||
<p>The parameter <tt>current_name</tt> is only used if a <span class="preprocessor">#include_next</span> directive
|
||||
was encountered (and <tt>BOOST_WAVE_SUPPORT_INCLUDE_NEXT</tt> was defined to be
|
||||
non-zero). In this case it points to unique full name of the current
|
||||
include file (if any). Otherwise this parameter is set to <tt>NULL</tt>.</p>
|
||||
|
||||
<p>The parameter <tt>dir_path</tt> on return is expected to hold the directory
|
||||
part of the located file.</p>
|
||||
|
||||
<p>The parameter <tt>native_name</tt> on return is expected to hold the unique
|
||||
full file name of the located file.</p>
|
||||
|
||||
<p>The return value defines whether the file was located successfully.</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>
|
||||
@@ -398,7 +470,7 @@
|
||||
<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>
|
||||
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_directive</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_directive</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);
|
||||
@@ -411,6 +483,33 @@
|
||||
<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>
|
||||
<p><strong><a name="emit_line_directive" id="emit_line_directive"></a>emit_line_directive</strong></p>
|
||||
<pre>
|
||||
<span class="keyword">template</span> <<span class="keyword">typename</span> <span class="type">ContextT</span>, <span class="keyword">typename</span> <span class="type">ContainerT</span>>
|
||||
<span class="type">bool</span> <span class="function-name">emit_line_directive</span>(<span class="type">ContextT</span> <span class="keyword">const</span>& <span class="variable-name">ctx</span>, <span class="type">ContainerT</span> &<span class="variable-name">pending</span>,
|
||||
<span class="keyword">typename</span> <span class="constant">ContextT</span>::<span class="type">token_type</span> <span class="keyword">const</span>& <span class="variable-name">act_token</span>);
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p>The function <tt>emit_line_directive</tt> is called whenever a <span class="preprocessor">#line</span> directive
|
||||
has to be emitted into the generated output.</p>
|
||||
|
||||
<p>The parameter <tt>ctx</tt> is a reference to the context object used for
|
||||
instantiating the preprocessing iterators by the user.</p>
|
||||
|
||||
<p>The parameter <tt>pending</tt> may be used to push tokens back into the input
|
||||
stream, which are to be used instead of the default output generated
|
||||
for the <span class="preprocessor">#line</span> directive.</p>
|
||||
|
||||
<p>The parameter <tt>act_token</tt> contains the actual <span class="preprocessor">#pragma</span> token, which may
|
||||
be used for error output. The line number stored in this token can be
|
||||
used as the line number emitted as part of the <span class="preprocessor">#line</span> directive.</p>
|
||||
|
||||
<p>If the return value is <tt>false</tt>, a default <span class="preprocessor">#line</span> directive is emitted
|
||||
by the library. A return value of <tt>true</tt> will inhibit any further
|
||||
actions, the tokens contained in <tt>pending</tt> will be copied verbatim
|
||||
to the output.</p>
|
||||
</blockquote>
|
||||
|
||||
<table border="0">
|
||||
<tbody>
|
||||
<tr>
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<p dir="ltr">The <tt>Wave</tt> library contains several samples illustrating how to use the different features. This section describes these samples and its main characteristics. </p>
|
||||
<p dir="ltr">The <tt>Wave</tt> library contains several samples illustrating how to use the different features. This section describes these samples and their main characteristics. </p>
|
||||
<h2 dir="ltr">The quick_start sample</h2>
|
||||
<p>The <tt>quick_start</tt> sample shows a minimal way to use the <tt>Wave</tt> preprocessor library. It simply opens the file given as the first command line argument, preprocesses it assuming that there aren't any additional include paths or macros defined and outputs the textual representation of the tokens generated from the given input file. This sample may be used to introduce yourself to <tt>Wave</tt>, because it does not contain all the potential additional complexity exposed by more complex samples. </p>
|
||||
<h2>The lexed_tokens sample</h2>
|
||||
@@ -49,7 +49,7 @@
|
||||
<span class="preprocessor"> # include</span> <span class="literal">"file_b.h"</span>
|
||||
<span class="preprocessor"> #endif</span></pre>
|
||||
<h2 dir="ltr">The advanced_hooks sample</h2>
|
||||
<p dir="ltr">The <tt>advanced_hooks</tt> sample is based on the <tt>quick_start</tt> sample mentioned above. It shows how you may want to use the advanced preprocessing hooks of the <tt>Wave</tt> library to get in the output not only the preprocessed tokens from the evaluated conditional blocks, but also the tokens recognized inside the non-evaluated conditional blocks. To make the generated token stream useful for further processing the tokens from the non-evaluated conditional blocks are commented out. </p>
|
||||
<p dir="ltr">The <tt>advanced_hooks</tt> sample is based on the <tt>quick_start</tt> sample mentioned above. It shows how you may want to use the <a href="class_reference_ctxpolicy.html#introduction">advanced preprocessing hooks</a> of the <tt>Wave</tt> library to get in the output not only the preprocessed tokens from the evaluated conditional blocks, but also the tokens recognized inside the non-evaluated conditional blocks. To make the generated token stream useful for further processing the tokens from the non-evaluated conditional blocks are commented out. </p>
|
||||
<p dir="ltr">Here is a small sample what the <tt>advanced_hooks</tt> sample does. Consider the following input: </p>
|
||||
<pre> <span class="preprocessor">#define</span> TEST 1
|
||||
<span class="preprocessor"> #if</span> <span class="keyword">defined</span>(TEST)
|
||||
@@ -67,7 +67,7 @@
|
||||
<h2 dir="ltr">The wave sample</h2>
|
||||
<p dir="ltr">Because of its general usefulness the <tt>wave</tt> sample is not located in the sample directory of the library, but inside the tools directory of Boost. The wave sample is usable as a full fledged preprocessor executable
|
||||
on top of any other C++ compiler. It outputs the textual representation of the
|
||||
preprocessed tokens generated from a given input file. It is described in more details <a href="wave_driver.html">here</a>. </p>
|
||||
preprocessed tokens generated from a given input file. It is described in more detail <a href="wave_driver.html">here</a>. </p>
|
||||
<h2 dir="ltr">The waveidl sample </h2>
|
||||
<p dir="ltr">The main point of the <tt>waveidl</tt> sample is to show, how a completely independent lexer type may be used in conjunction with the default token type of the <tt>Wave</tt> library. The lexer used in this sample is supposed to be used for an IDL language based preprocessor. It is based on the <tt>Re2C</tt> tool too, but recognizes a different set of tokens as the default C++ lexer contained within the <tt>Wave</tt> library. So this lexer does not recognize any keywords (except <tt>true</tt> and <tt>false</tt>, which are needed by the preprocessor itself). This is needed because there exist different IDL languages, where identifiers of one language may be keywords of others. Certainly this implies to postpone keyword identification after the preprocessing, but allows to use <tt>Wave</tt> for all of the IDL derivatives. </p>
|
||||
<p dir="ltr">It is only possible to use the <tt>Wave</tt> library to write an IDL preprocessor, because the token sets for both languages are very similar. The tokens to be recognized by the <tt>waveidl</tt> IDL language preprocessor is nearly a complete subset of the full C++ token set. </p>
|
||||
@@ -95,7 +95,7 @@ preprocessed tokens generated from a given input file. It is described in more d
|
||||
<p>It may be a good starting point for a grammar that can be used for things like reverse engineering as some UML modelling tools do. Or whatever use you may find for a grammar that gives you a list of all templates and classes in a file and their members. <br>
|
||||
</p>
|
||||
<h2 dir="ltr">The check_macro_naming sample</h2>
|
||||
<p>The <tt>check_macro_naming</tt> sample demonstrates the use of context hooks to understand how macros are defined within a codebase. Some projects (such as Boost itself) have conventions on the names of macros. This sample will recursively search a directory, looking for header files and searching each for macro definitions. Any that do not match the supplied convention (which defaults to <tt>^BOOST_.*</tt>) are reported, along with an annotation if they are used as an include guard. The user can also specify any number of directories to ignore in the process.</p>
|
||||
<p>The <tt>check_macro_naming</tt> sample demonstrates the use of <a href="class_reference_ctxpolicy.html#introduction">context hooks</a> to understand how macros are defined within a codebase. Some projects (such as Boost itself) have conventions on the names of macros. This sample will recursively search a directory, looking for header files and searching each for macro definitions. Any that do not match the supplied convention (which defaults to <tt>^BOOST_.*</tt>) are reported, along with an annotation if they are used as an include guard. The user can also specify any number of directories to ignore in the process.</p>
|
||||
<p dir="ltr">Command line syntax:</p>
|
||||
<pre>
|
||||
Usage: check_macro_naming [options] directory:
|
||||
@@ -113,6 +113,33 @@ TRACE_CPP_TIME_CONVERSION include/boost/wave/util/time_conversion_helper.hpp
|
||||
spirit_append_actor include/boost/wave/util/time_conversion_helper.hpp
|
||||
spirit_assign_actor include/boost/wave/util/time_conversion_helper.hpp
|
||||
</pre>
|
||||
<h2 dir="ltr">The custom_directives sample</h2>
|
||||
<p>The <tt>custom_directives</tt> sample shows how to define your own directives by overriding the <a href="class_reference_ctxpolicy.html#found_unknown_directive">found_unknown_directive</a> hook to add <tt>#version</tt> and <tt>#extension</tt> directives (from GLSL).</p>
|
||||
<h2 dir="ltr">The emit_custom_line_directives sample</h2>
|
||||
<p>The <tt>emit_custom_line_directives</tt> sample shows how to use the <a href="class_reference_ctxpolicy.html#emit_line_directive">emit_line_directive</a> preprocessing hook
|
||||
to customize the format of any generated <span class="preprocessor">#line</span> directive. The sample will
|
||||
emit #line directives formatted compatible with those generated by gcc:</p>
|
||||
<pre>
|
||||
# <lineno> <rel_file_name>
|
||||
</pre>
|
||||
<h2 dir="ltr">The preprocess_pragma_output sample</h2>
|
||||
<p>The <tt>preprocess_pragma_output</tt> sample demonstrates using the <a href="class_reference_ctxpolicy.html#interpret_pragma">interpret_pragma</a> hook to install custom pragma handling code. Specifically it defines a new <tt>#pragma wave pp()</tt> that interprets a string in the current preprocessor context. The sample input uses this mechanism to define new macros from within a quoted string passed to <tt>pp</tt>.
|
||||
<h2 dir="ltr">The real_positions sample</h2>
|
||||
The <tt>real_positions</tt> sample demonstrates:
|
||||
<ul>
|
||||
<li>the use of the <a href="class_reference_ctxpolicy.html#generated_token">generated_token</a> hook</li>
|
||||
<li>how to use Wave with a new token type without changing the lexer</li>
|
||||
</ul>
|
||||
<p>by showing how to correct the positions inside the returned tokens in
|
||||
a way that these appear to be consecutive (ignoring positions from macro
|
||||
definitions).</p>
|
||||
|
||||
<h2 dir="ltr">The token_statistics sample</h2>
|
||||
The <tt>token_statistics</tt> sample collects counts of each type of token in the preprocessed input and reports it. It demonstrates:
|
||||
<ul>
|
||||
<li>Using the Xpressive lexer</li>
|
||||
<li>Setting custom local and system include search paths</li>
|
||||
</ul>
|
||||
<table border="0">
|
||||
<tr>
|
||||
<td width="10"></td>
|
||||
|
||||
Reference in New Issue
Block a user