#

Supported Pragma Directives

The Wave preprocessor library supports a couple of specific `#pragma` directives, which may be used to control some of the library features. All directives described here are usable as conventional `#pragma` directives and as `operator _Pragma` (if variadics are enabled). So for instance the following directives are functionally identical:

        #pragma wave trace(enable)

and

        _Pragma("wave trace(enable)")

All `Wave` specific pragma's must have the general form `'wave option[(value)]'`, where `'wave'` is the specific keyword, `'option'` is the concrete pragma functionality to trigger and `'value'` is an optional value to be supplied to the `'option'` functionality. The following table lists all possible pragma functions supported by the `Wave` library. For all recognised pragmas of this general form the interpret_pragma hook function from inside the context_policies are call, so that the user of the library is responsible for

Supported pragma's
trace | enable/on/1 disable/off/0 | Enable or disable the tracing of the macro expansion process. This is needed, even if there is given the --trace command line option, because the trace output is generated only, if there is at least one trace(enable) pragma found. | Wave driver
stop | message | Stop the execution of `Wave` and print out the given message. This is very helpful for direct debugging purposes. | Wave driver
system | command | Try to spawn the 'command' as a new operating system command and intercept the generated stdout and stderr. The stdout output of this command (if any) is retokenized and used as the replacement text for the whole pragma, the stderr output is ignored. The command is considered to be successful, if/when the return value is zero, otherwise an error is reported. | Wave driver
timer | restart/0 <no value> suspend resume | The value `restart` set the current elapsed time to 0 and restarts the timer. If no value is provided, the current elpsed time is printed to the std::cerr stream. The values `suspend` and `resume` allow to temporarily stop the timing. | Wave driver

All pragma's not listed here but flagged as `'wave'` are reported as errors. The handling of all remaining pragma's depends on the compilation constant ``WAVE_RETURN_PRAGMA_DIRECTIVES``, which allows to specify, if those pragmas are left unchanged in the output stream or not. Please note, that the operator _Pragma variant is always subject to full preprocessing, before the pragma itself is evaluated. The #pragma variant is subject to preprocessing only, if the ``WAVE_PREPROCESS_PRAGMA_BODY`` compilation constant was specified during compilation. For more information about the possible compilation constants look here.

Additionally the Wave preprocessor supports the `#pragma once` directive, which specifies that the file, in which the pragma resides, will be included (opened) only once by the compiler in a build. This may be used to optimize the preprocessing of larger compilation units, which include a lot of files. Note though, that the #pragma once directive is supported only, if the compile time constant `WAVE_SUPPORT_PRAGMA_ONCE` was given during compilation of the library.

It is fairly easy to implement your own `#pragma wave ...` directives. All you have to do is to implement your own `interpret_pragma` function (see here) which should the handle additional directives. For an example of how to do it, you may have a look at the Wave driver application, which implements the `#pragma wave timer()` directive with the help of a supplied `interpret_pragma` function.

Copyright © 2003-2005 Hartmut Kaiser
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)

Last updated: Sunday, May 15, 2005 12:23