| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <title>Supported Pragma Directives</title> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 6 | <link href="theme/style.css" rel="stylesheet" type="text/css"> |
|---|
| 7 | </head> |
|---|
| 8 | |
|---|
| 9 | <body> |
|---|
| 10 | <table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif"> |
|---|
| 11 | <tr> |
|---|
| 12 | <td width="21"> <h1></h1></td> |
|---|
| 13 | <td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">Supported |
|---|
| 14 | Pragma Directives</font></b></font></td> |
|---|
| 15 | <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td> |
|---|
| 16 | </tr> |
|---|
| 17 | </table> |
|---|
| 18 | <br> |
|---|
| 19 | <table border="0"> |
|---|
| 20 | <tr> |
|---|
| 21 | <td width="10"></td> |
|---|
| 22 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
|---|
| 23 | <td width="30"><a href="tracing_facility.html"><img src="theme/l_arr.gif" border="0"></a></td> |
|---|
| 24 | <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td> |
|---|
| 25 | </tr> |
|---|
| 26 | </table> |
|---|
| 27 | <blockquote> |
|---|
| 28 | <p><a href="supported_pragmas.html#library_pragmas">Pragma directives supported by the Wave library</a><br> |
|---|
| 29 | <a href="supported_pragmas.html#tool_pragmas">Pragma directives supported by the Wave tool</a></p> |
|---|
| 30 | </blockquote> |
|---|
| 31 | <h2><a name="library_pragmas"></a>Pragma directives supported by the Wave library </h2> |
|---|
| 32 | <p>The <tt>Wave</tt> preprocessor library natively supports the <span class="preprocessor">#pragma once</span> and <span class="preprocessor">#pragma message("...")</span> directives. </p> |
|---|
| 33 | <p>The <span class="preprocessor">#pragma once</span> directive specifies that the file in which the pragma resides will be included |
|---|
| 34 | (opened) only once. This may be used to optimize |
|---|
| 35 | the preprocessing of larger compilation units, which include a lot of files. Note though, that the <span class="preprocessor">#pragma once</span> directive is supported only, if the compile time constant <tt>BOOST_WAVE_SUPPORT_PRAGMA_ONCE</tt> was given during compilation of the library.</p> |
|---|
| 36 | <p>The <span class="preprocessor">#pragma message(...)</span> directive generates a remark containing the given message text. This may be useful to generate status messages directly from the preprocessed file. Note though, that the #pragma message(...) directive is supported only, if the compile time constant <tt>BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE</tt> was given during the compilation of the library. Note additionally, that the body of the message is preprocessed whenever the <tt>BOOST_WAVE_PREPROCESS_PRAGMA_BODY</tt> compile time constant was defined during compilation of the library. </p> |
|---|
| 37 | <h2><a name="tool_pragmas"></a>Pragma directives supported by the Wave tool</h2> |
|---|
| 38 | <p>The Wave preprocessor tool additionally supports specific <span class="preprocessor">#pragma</span> directives, which may be used to control some of the tools features. These <span class="preprocessor">#pragma</span> directives are implemented using the <tt>interpret_pragma()</tt> preprocessing hook (see <a href="class_reference_ctxpolicy.html#interpret_pragma">here</a>).</p> |
|---|
| 39 | <p>All directives |
|---|
| 40 | described here are usable as conventional <span class="preprocessor">#pragma</span> directives and as <span class="preprocessor">operator _Pragma</span> (if variadics are enabled). So for instance the |
|---|
| 41 | following directives are functionally identical:</p> |
|---|
| 42 | <pre> #pragma wave trace(enable) </pre> |
|---|
| 43 | <p>and </p> |
|---|
| 44 | <pre> _Pragma("wave trace(enable)")</pre> |
|---|
| 45 | <p>All <tt>Wave</tt> specific pragma's must have the general form <tt>'wave option[(value)]'</tt>, |
|---|
| 46 | where <tt>'wave'</tt> is the specific keyword (which may be configured through the <tt>BOOST_WAVE_PRAGMA_KEYWORD</tt> compile time constant, see <a href="compiletime_config.html">here</a> for more information), <tt>'option'</tt> is the concrete |
|---|
| 47 | pragma functionality to trigger and <tt>'value'</tt> is an optional value to |
|---|
| 48 | be supplied to the <tt>'option'</tt> functionality. The following table lists |
|---|
| 49 | all possible pragma functions supported by the <tt>Wave</tt> library. For all recognised pragmas of this general form the interpret_pragma hook function from inside the <a href="class_reference_ctxpolicy.html">preprocessing_hooks</a> policy are called, so that the user of the library is responsible for the correct interpretation of these pragma's. </p> |
|---|
| 50 | <table width="77%" border="0" align="center"> |
|---|
| 51 | <tr> |
|---|
| 52 | <td colspan="3"> <p class="table_title">Supported pragma's</p></td> |
|---|
| 53 | </tr> |
|---|
| 54 | <tr> |
|---|
| 55 | <td> <p class="toc_title" width="36%">pragma option</p></td> |
|---|
| 56 | <td> <p class="toc_title" width="28%">pragma value</p></td> |
|---|
| 57 | <td> <p class="toc_title" width="36%">description</p></td> |
|---|
| 58 | </tr> |
|---|
| 59 | <tr> |
|---|
| 60 | <td class="table_cells" width="19%"> <p>trace</p></td> |
|---|
| 61 | <td class="table_cells" width="18%"> <p>enable/on/1<br> |
|---|
| 62 | disable/off/0</p></td> |
|---|
| 63 | <td class="table_cells" width="43%"><p>Enable or disable the tracing of the |
|---|
| 64 | macro expansion process. This is needed, even if there is given the --trace |
|---|
| 65 | command line option, because the trace output is generated only, if there |
|---|
| 66 | is at least one trace(enable) pragma found.</p></td> |
|---|
| 67 | </tr> |
|---|
| 68 | <tr> |
|---|
| 69 | <td class="table_cells"><p>stop</p></td> |
|---|
| 70 | <td class="table_cells"><p>message</p></td> |
|---|
| 71 | <td class="table_cells"><p>Stop the execution of <tt>Wave</tt> and print out |
|---|
| 72 | the given message. This is very helpful for direct debugging purposes.</p></td> |
|---|
| 73 | </tr> |
|---|
| 74 | |
|---|
| 75 | <tr> |
|---|
| 76 | <td class="table_cells"><p>system</p></td> |
|---|
| 77 | <td class="table_cells"><p>command</p></td> |
|---|
| 78 | <td class="table_cells"><p>Try to spawn the 'command' as a new operating system |
|---|
| 79 | command and intercept the generated stdout and stderr. The stdout output |
|---|
| 80 | of this command (if any) is retokenized and used as the replacement text |
|---|
| 81 | for the whole pragma, the stderr output is ignored. The command is considered |
|---|
| 82 | to be successful, if/when the return value is zero, otherwise an error |
|---|
| 83 | is reported. <br> |
|---|
| 84 | This <span class="preprocessor">#pragma</span> is available only if the command line option -x is specified. The <tt>Wave</tt> driver will issue a remark if this command line argument is not specified and a <span class="preprocessor">#pragma wave system()</span> directive is encountered<br> |
|---|
| 85 | </p></td> |
|---|
| 86 | </tr> |
|---|
| 87 | <tr> |
|---|
| 88 | <td class="table_cells"><p>timer</p></td> |
|---|
| 89 | <td class="table_cells"><p> restart/0<br> |
|---|
| 90 | <no value> <br> |
|---|
| 91 | suspend<br> |
|---|
| 92 | resume </p></td> |
|---|
| 93 | <td class="table_cells"><p>The value <tt>restart</tt> set the current elapsed |
|---|
| 94 | time to 0 and restarts the timer.</p> |
|---|
| 95 | <p> If no value is provided, the current elapsed time is printed to the std::cerr |
|---|
| 96 | stream. </p> |
|---|
| 97 | <p>The values <tt>suspend</tt> and <tt>resume</tt> allow to temporarily stop |
|---|
| 98 | and resume the timing.</p></td> |
|---|
| 99 | </tr> |
|---|
| 100 | <tr> |
|---|
| 101 | <td class="table_cells"><p>option</p></td> |
|---|
| 102 | <td class="table_cells"><p>line: [0|1]<br> |
|---|
| 103 | preserve: [0|1|2]<br> |
|---|
| 104 | output: ["filename" | null] |
|---|
| 105 | </p> |
|---|
| 106 | </td> |
|---|
| 107 | <td class="table_cells"><p>The <tt>option(line: ...)</tt> directive allows to control, whether <span class="preprocessor">#line</span> directives will be generated in the output stream. Specify either '0' or '1' as the option parameter. All other values will be flaged as illegal. </p> |
|---|
| 108 | <p>The <tt>option(preserve: ...)</tt> directive allows to control the amount of whitespace generated in the output stream. The value '0' removes any not needed whitespace, the value '1' keeps comments only and the value '2' does not remove any whitespace.</p> |
|---|
| 109 | <p>The <tt>option(output: ...)</tt> directive allows to specify the name of the file, where the output is generated to. Specify either a valid filename (which will be interpreted relative to directory of the processed file) or the value <tt>null</tt> (without quotes) to disable the output at all. </p></td> |
|---|
| 110 | </tr> |
|---|
| 111 | </table> |
|---|
| 112 | <p>All pragma's not listed here but flagged as <tt>'wave'</tt> are currently reported as |
|---|
| 113 | errors. The handling of all remaining pragma's depends on the compilation constant |
|---|
| 114 | <code><tt>BOOST_WAVE_RETURN_PRAGMA_DIRECTIVES</tt></code>, which allows to specify, |
|---|
| 115 | if those pragmas are left unchanged in the output stream or not. Please note, |
|---|
| 116 | that the operator _Pragma variant is always subject to full preprocessing, before |
|---|
| 117 | the pragma itself is evaluated. The #pragma variant is subject to preprocessing |
|---|
| 118 | only, if the <code><tt>BOOST_WAVE_PREPROCESS_PRAGMA_BODY</tt></code> compilation constant |
|---|
| 119 | was specified during compilation. For more information about the possible compilation |
|---|
| 120 | constants look <a href="compiletime_config.html">here</a>.</p> |
|---|
| 121 | <p>It is fairly easy to implement your own <span class="preprocessor">#pragma wave ...</span> directives. All you have to do is to implement your own <tt>interpret_pragma</tt> preprocessing hook function (see <a href="class_reference_ctxpolicy.html#interpret_pragma">here</a>) which should handle the additional directives. For an example of how to do it, you may have a look at the Wave driver application, which implements all of the pragma's listed above with the help of a supplied <tt>interpret_pragma</tt> function (for instance the <span class="preprocessor">#pragma wave timer()</span> directive). </p> |
|---|
| 122 | <table border="0"> |
|---|
| 123 | <tr> |
|---|
| 124 | <td width="10"></td> |
|---|
| 125 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> |
|---|
| 126 | <td width="30"><a href="tracing_facility.html"><img src="theme/l_arr.gif" border="0"></a></td> |
|---|
| 127 | <td width="30"><a href="acknowledgements.html"><img src="theme/r_arr.gif" border="0"></a></td> |
|---|
| 128 | </tr> |
|---|
| 129 | </table> |
|---|
| 130 | <hr size="1"> |
|---|
| 131 | <p class="copyright">Copyright © 2003-2007 Hartmut Kaiser<br> |
|---|
| 132 | <br> |
|---|
| 133 | <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> |
|---|
| 134 | <span class="updated"></span> |
|---|
| 135 | <p class="copyright"><span class="updated">Last updated: |
|---|
| 136 | <!-- #BeginDate format:fcAm1m -->Tuesday, May 2, 2006 17:28<!-- #EndDate --> |
|---|
| 137 | </span> |
|---|
| 138 | </p> |
|---|
| 139 | <p> </p> |
|---|
| 140 | </body> |
|---|
| 141 | </html> |
|---|
