mirror of
https://github.com/boostorg/wave.git
synced 2026-01-27 07:22:15 +00:00
250 lines
16 KiB
HTML
250 lines
16 KiB
HTML
<!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> boost {
|
|
<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, language_support language);
|
|
};
|
|
|
|
} <span class="comment">// namespace macro_trace_policy</span>
|
|
} <span <!-- #BeginDate format:fcAm1m -->Wednesday, January 14, 2004 12:46<!-- #EndDate -->st</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, 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 -->Wednesday, January 14, 2004 12:36<!-- #EndDate -->
|
|
</span></body>
|
|
</html>
|