Click here to Skip to main content
Click here to Skip to main content
Add your own
alternative version
Go to top

Wave: a Standard conformant C++ preprocessor library

, 10 Jan 2004
Describes a free and fully Standard conformant C++ preprocessor library
wave_preprocessor_demo.zip
wave.exe
wave_preprocessor_demo1.zip
wave.exe
wave_preprocessor_src.zip
wave
doc
theme
bkd.gif
bkd2.gif
bullet.gif
l_arr.gif
l_arr_disabled.gif
r_arr.gif
r_arr_disabled.gif
uc.gif
u_arr.gif
wave.gif
test
boost-build.jam
cpp_tokens
Jamfile.v2
list_includes
project-root.jam
wave
Jamfile
Jamfile.v2
runtests.sh
test_files
wave
cpplexer
re2clex
cpp.re
test
lextest.in
lextest.output
run_tests.sh
test_lexer.in
test_lexer.output
slex
test
lextest.in
lextest.re2c.output
lextest.slex.output
run_tests.sh
grammars
idllexer
re2clex
idl.re
util
wave_preprocessor_src1.zip
bkd.gif
bkd2.gif
bullet.gif
l_arr.gif
l_arr_disabled.gif
r_arr.gif
r_arr_disabled.gif
u_arr.gif
uc.gif
wave.gif
boost-build.jam
Jamfile.v2
project-root.jam
Jamfile
Jamfile.v2
runtests.sh
cpp.re
lextest.in
lextest.output
run_tests.sh
test_lexer.in
test_lexer.output
lextest.in
lextest.re2c.output
lextest.slex.output
run_tests.sh
<!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&nbsp;wave_option(trace:&nbsp;enable)</tt> 
  (or <tt>_Pragma(&quot;wave&nbsp;trace(enable)&quot;)</tt>) directive. The macro 
  tracing may be disabled again with the help of a <tt>#pragma wave_option(trace: 
  disable)</tt> (or <tt>_Pragma(&quot;wave&nbsp;trace(disable)&quot;)</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&lt;&gt;</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> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
        <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> &amp;macrodef, 
            <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args, 
            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall, 
            <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;arguments);
 
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
        <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> &amp;macro, 
            ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall);
 
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
        <span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">expanded_macro</a>(ContainerT <span class="keyword">const</span> &amp;result);
 
        <span class="keyword">template</span> &lt;<span class="keyword">typename</span> ContainerT&gt;
        <span class="keyword">void</span> <a href="class_reference_tracepolicy.html#expanded_macro">rescanned_macro</a>(ContainerT <span class="keyword">const</span> &amp;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> &amp;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> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
		        bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &amp;pending, 
             TokenT const &amp;option, ContainerT <span class="keyword">const</span> &amp;values, 
             TokenT <span class="keyword">const</span> &amp;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> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
    <span class="keyword">void</span> expanding_function_like_macro(TokenT <span class="keyword">const</span> &amp;macrodef, 
        <span class="keyword">std::vector</span>&lt;TokenT&gt; <span class="keyword">const</span> &amp;formal_args, 
        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;macrocall, 
        <span class="keyword">std::vector</span>&lt;ContainerT&gt; <span class="keyword">const</span> &amp;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> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
    <span class="keyword">void</span> expanding_object_like_macro(TokenT <span class="keyword">const</span> &amp;macro, 
        ContainerT <span class="keyword">const</span> &amp;definition, TokenT <span class="keyword">const</span> &amp;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> &lt;<span class="keyword">typename</span> ContainerT&gt;
    <span class="keyword">void</span> expanded_macro(ContainerT <span class="keyword">const</span> &amp;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> &lt;<span class="keyword">typename</span> ContainerT&gt;
    <span class="keyword">void</span> rescanned_macro(ContainerT <span class="keyword">const</span> &amp;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> &amp;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&nbsp;&lt;...&gt;</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> &lt;<span class="keyword">typename</span> TokenT, <span class="keyword">typename</span> ContainerT&gt;
		   bool <a href="class_reference_tracepolicy.html#interpret_pragma">interpret_pragma</a>(ContainerT &amp;pending, 
        TokenT const &amp;option, ContainerT <span class="keyword">const</span> &amp;values, 
        TokenT <span class="keyword">const</span> &amp;pragma_token, 
        wave::language_support language);
</pre>
<blockquote> 
  <p>The function <tt>interpret_pragma</tt> is called, whenever an unrecognized 
    <tt>#pragma&nbsp;wave&nbsp;...</tt> or operator <tt>_Pragma(&quot;wave&nbsp;...&quot;)</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&nbsp;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 &copy; 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>

By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Hartmut Kaiser

United States United States
Actively involved in Boost and the development of the Spirit parser construction framework.

| Advertise | Privacy | Mobile
Web02 | 2.8.140926.1 | Last Updated 11 Jan 2004
Article Copyright 2003 by Hartmut Kaiser
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid