<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The Tracing Policy</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="theme/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
<tr>
<td width="21"> <h1></h1></td>
<td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The
Tracing Policy</font></b></font></td>
<td width="96"><a href="http://spirit.sf.net"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
</tr>
</table>
<br>
<table border="0">
<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_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<blockquote>
<p><a href="class_reference_tracepolicy.html#introduction">Introduction</a><br>
<a href="class_reference_tracepolicy.html#header_synopsis">Header 'wave/trace_policies.hpp'
synopsis</a><br>
<a href="class_reference_tracepolicy.html#member_functions">Member functions</a></p>
</blockquote>
<h2><b><a name="introduction"></a>Introduction</b></h2>
<p>There is implemented an unique tracing facility as a part of the <tt>Wave</tt>
library, which allows to selectively trace all stages of the macro expansion
process, involving the argument expansion and the rescanning of the replacement
results. This tracing facility greatly helps to understand foreign code or to
debug your own macros.</p>
<p>The tracing policy is used to trace the macro expansion of macros whenever
it is requested from inside the input stream to preprocess through the <tt>#pragma wave_option(trace: enable)</tt>
(or <tt>_Pragma("wave trace(enable)")</tt>) directive. The macro
tracing may be disabled again with the help of a <tt>#pragma wave_option(trace:
disable)</tt> (or <tt>_Pragma("wave trace(disable)")</tt>) directive.
Note though, that the <tt>Wave</tt> driver executable requires additionally
to specify the <tt>-t</tt> (<tt>--trace</tt>) command line option, which defines
the stream, where the trace output goes.</p>
<p>This policy type is used as a template parameter to the <a href="class_reference_context.html"><tt>wave::context<></tt></a>
object, where the default policy does no tracing at all.</p>
<h2><a name="header_synopsis"></a>Header <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/spirit/spirit/wave/wave/macro_trace_policies.hpp?rev=1.1&content-type=text/vnd.viewcvs-markup">wave/trace_policies.hpp</a>
synopsis</h2>
<pre>
<span class="keyword">namespace</span> wave {
<span class="keyword">namespace</span> trace_policies {
<span class="keyword">enum</span> trace_flags {
trace_nothing = 0, <span class="comment">// disable tracing</span>
trace_macros = 1, <span class="comment">// enable macro tracing</span>
trace_includes = 2 <span class="comment">// enable include file tracing</span>
};
<span class="keyword">struct</span> default_tracing {
<span class="comment">// general control function</span>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#enable_tracing">enable_tracing</a>(trace_flags enable);
trace_flags <a href="class_reference_tracepolicy.html#tracing_enabled">tracing_enabled</a>();
<span class="comment">// macro tracing functions</span>
<span class="keyword">template</span> <<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanding_function_like_macro">expanding_function_like_macro</a>(TokenT <span class="keyword">const</span> &macrodef,
<span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args,
ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall,
<span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments);
<span class="keyword">template</span> <<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanding_object_like_macro">expanding_object_like_macro</a>(TokenT <span class="keyword">const</span> &macro,
ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall);
<span class="keyword">template</span> <<span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">expanded_macro</a>(ContainerT <span class="keyword">const</span> &result);
<span class="keyword">template</span> <<span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">rescanned_macro</a>(ContainerT <span class="keyword">const</span> &result);
<span class="comment">// include file tracing functions</span>
<span class="keyword">void </span><a href="class_reference_tracepolicy.html#opened_include_file">opened_include_file</a>(std::string <span class="keyword">const</span> &filename,
std::size_t include_depth, <span class="keyword">bool</span> is_system_include);
<span class="keyword">void</span> <a href="class_reference_tracepolicy.html#returning_from_include_file">returning_from_include_file</a>();
<span class="comment">// interpretation of unknown #pragma's</span>
<span class="keyword">template</span> <<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &pending,
TokenT const &option, ContainerT <span class="keyword">const</span> &values,
TokenT <span class="keyword">const</span> &pragma_token,
wave::language_support language);
};
} <span class="comment">// namespace macro_trace_policy</span>
} <span class="comment">// namespace wave</span>
</pre>
<h2><a name="member_functions"></a>Member functions</h2>
<h3>General control functions</h3>
<p><a name="enable_tracing"></a><b>enable_tracing</b></p>
<pre> <span class="keyword">void</span> enable_tracing(<span class="keyword">trace_flags</span> enable);</pre>
<blockquote>
<p>The function <tt>enable_tracing</tt> is called, whenever the status of the
tracing was changed from inside the stream to preprocess.</p>
<p>The parameter <tt>enable</tt> is to be used as the new tracing status.</p>
</blockquote>
<p><a name="tracing_enabled"></a><b>tracing_enabled</b></p>
<pre> <span class="keyword">trace_flags</span> tracing_enabled();</pre>
<blockquote>
<p>The function <tt>tracing_enabled</tt> should return the current tracing status.</p>
</blockquote>
<h3>Tracing functions</h3>
<h4>Macro tracing functions</h4>
<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> TokenT, <span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> expanding_function_like_macro(TokenT <span class="keyword">const</span> &macrodef,
<span class="keyword">std::vector</span><TokenT> <span class="keyword">const</span> &formal_args,
ContainerT <span class="keyword">const</span> &definition, TokenT <span class="keyword">const</span> &macrocall,
<span class="keyword">std::vector</span><ContainerT> <span class="keyword">const</span> &arguments);</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>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 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>
</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> TokenT, <span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> expanding_object_like_macro(TokenT <span class="keyword">const</span> &macro,
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>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 invoked.
It contains the token, which identifies the macro call inside the preprocessed
input stream. </p>
</blockquote>
<p><a name="expanded_macro"></a><b>expanded_macro</b></p>
<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> ContainerT>
<span class="keyword">void</span> expanded_macro(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 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> ContainerT>
<span class="keyword">void</span> rescanned_macro(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 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>
<h4>Include file tracing functions</h4>
<p><a name="opened_include_file" id="opened_include_file"></a><strong>opened_include_file</strong></p>
<pre> <span class="keyword">void</span> opened_include_file(std::string <span class="keyword">const</span> &filename,
std::size_t include_depth, <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 #include directive was successfully located and opened.</p>
<p>The parameter <tt>filename</tt> contains the full file system path of the
opened file.</p>
<p>The <tt>include_depth</tt> parameter contains the current include file depth.
</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">void</span> returning_from_include_file();
</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>
</blockquote>
<p><strong><a name="interpret_pragma"></a>interpret_pragma</strong></p>
<pre> <span class="keyword">template</span> <<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT>
bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &pending,
TokenT const &option, ContainerT <span class="keyword">const</span> &values,
TokenT <span class="keyword">const</span> &pragma_token,
wave::language_support language);
</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>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>The <tt>language</tt> parameter contains the current language mode, in which
the <tt>Wave</tt> library operates.</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>
<table border="0">
<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_inputpolicy.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
<td width="30"><a href="class_reference_lexer.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<hr size="1">
<p class="copyright">Copyright © 2003-2004 Hartmut Kaiser<br>
<br>
<font size="2">Use, modification and distribution is subject to 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>
<span class="updated">Last updated:
<!-- #BeginDate format:fcAm1m -->Monday, January 5, 2004 14:57<!-- #EndDate -->
</span></body>
</html>
Submit an article or tip