Supported Pragma Directives
支持的pragma指令

Pragma directives supported by the Wave library  Wave庫所支持的Pragma指令
Pragma directives supported by the Wave tool  Wave工具所支持的Pragma指令

Pragma directives supported by the Wave library  Wave庫所支持的Pragma指令

The Wave preprocessor library natively supports the #pragma once and #pragma message("...") directives.
Wave 預處理器庫本身支持 #pragma once#pragma message("...") 指令。

The #pragma once directive specifies that the file in which the pragma resides will be included (opened) only once. 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 BOOST_WAVE_SUPPORT_PRAGMA_ONCE was given during compilation of the library.
指令 #pragma once 指定該 pragma 所在的文件只能被包含(打開)一次。這可以用於對較大編譯單元的預處理器進行優化,這些編譯單元通常會包含大量文件。注意,指令 #pragma once 僅當在編譯本庫時給定了編譯期常量 BOOST_WAVE_SUPPORT_PRAGMA_ONCE 時方可支持。

The #pragma message(...) 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 BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE was given during the compilation of the library. Note additionally, that the body of the message is preprocessed whenever the BOOST_WAVE_PREPROCESS_PRAGMA_BODY compile time constant was defined during compilation of the library.
指令 #pragma message(...) 生成一個包含給定信息文本的標記。可用於從預處理文件直接生成狀態信息。注意,指令 #pragma message(...) 僅當在編譯本庫時給定了編譯期常量 BOOST_WAVE_SUPPORT_PRAGMA_MESSAGE 時方可支持。另外還要注意,只要在編譯本庫時給定了編譯期常量 BOOST_WAVE_PREPROCESS_PRAGMA_BODY,信息體就會被進行預處理。

Pragma directives supported by the Wave tool  Wave工具所支持的Pragma指令

The Wave preprocessor tool additionally supports specific #pragma directives, which may be used to control some of the tools features. These #pragma directives are implemented using the interpret_pragma() preprocessing hook (see here).
Wave 預處理器工具也支持一些專門的 #pragma 指令,可用於控制工具的某些特性。這些 #pragma 指令是用 interpret_pragma() 預處理鉤子實現的(請見這裡)。

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 指令和用作 operator _Pragma (如果啟用了 variadics)。因此,以下指令在功能上是一樣的:

    #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 (which may be configured through the BOOST_WAVE_PRAGMA_KEYWORD compile time constant, see here for more information), '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 preprocessing_hooks policy are called, so that the user of the library is responsible for the correct interpretation of these pragma's.
所有的 Wave 專用 pragma 必須具有一般形式 'wave option[(value)]',其中 'wave' 為專用的關鍵字(可以通過編譯期常量 BOOST_WAVE_PRAGMA_KEYWORD 來配置,更多信息請見這裡),'option' 為要觸發的具體 pragma 功能,'value' 是一個可選值,提供給 'option'。下表列出了 Wave 庫支持的所有 pragma 功能。對於所有具有此形式的、被識別出來的 pragmas,將會調用 preprocessing_hooks 策略中的 interpret_pragma 鉤子,因此庫用戶要負責對這些 pragma 進行正確的解釋。

Supported pragma's
支持的 pragma

pragma option

pragma value
pragma值

description 
說明

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.
啟用或禁用對宏展開過程的跟蹤。即使已經在命令行中給定 --trace 選項,也還需要這個,因為跟蹤輸出僅當至少找到一個 trace(enable) pragma 時才生成。

stop

message

Stop the execution of Wave and print out the given message. This is very helpful for direct debugging purposes.
停止 Wave 的執行並打印出給定的信息。對於直接的調試有用。

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.
This #pragma is available only if the command line option -x is specified. The Wave driver will issue a remark if this command line argument is not specified and a #pragma wave system() directive is encountered
嘗 試 spawn 出一個新的操作系統命令 'command',並截取生成的 stdout 和 stderr。該命令的 stdout 輸出(如果有)被重新分詞並用於替換掉整個 pragma 的文本,stderr 輸出則被忽略。當該命令的返回值為零時,認為命令執行成功,否則報告一個錯誤。
這個 #pragma 僅當指定了命令行選項 -x 時有效。如果該選項未指定且遇到一個 #pragma wave system() 指令,則 Wave 驅動器將產生一個標記。

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 elapsed time is printed to the std::cerr stream.

The values suspend and resume allow to temporarily stop and resume the timing.

restart 設置將當前的運行時間為 0,重新開始計時。
如果未提供值,則將當前運行時間打印到 std::cerr 流。
suspendresume 可以臨時停止和恢復計時。

option

line: [0 | 1 | push | pop]
preserve: [0 | 1 | 2 | push | pop]
output: ["filename" | null | default | push | pop]

The option(line: ...) directive allows to control, whether #line 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.

The option(preserve: ...) 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.

The option(output: ...) 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), the value null to disable the output at all, or the value default to use the output as specified on the command line using the --output/-o option.

The pragma values push and pop may be used for all of the options (line, preserve and output) to store and restore the current value of the corresponding option.

指令 option(line: ...) 可以控制是否在輸出流中生成 #line 指令。以 '0' 或 '1' 為選項參數。所有其它值將被標誌為非法。
指令 option(preserve: ...) 可以控制在輸出流中生成的空白數量。值 '0' 刪除所有非必要的空白,值 '1' 則只保留註釋,值 '2' 則不刪除任何空白。
指令 option(output: ...) 可以指定輸出的文件名。要麼指定一個有效的文件名(按相對於被處理文件的目錄來解釋),值 null 則禁止輸出,要麼使用值 default 來表示在命令行中以 --output/-o 選項指定的文件。
pragma 值 pushpop 可用於以上所有選項(line, preserveoutput),以保存和恢復相應選項的當前值。

All pragma's not listed here but flagged as 'wave' are currently reported as errors. The handling of all remaining pragma's depends on the compilation constant BOOST_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 BOOST_WAVE_PREPROCESS_PRAGMA_BODY compilation constant was specified during compilation. For more information about the possible compilation constants look here.
所有帶有 'wave' 標誌而又沒有在上表列出的 pragma 目前都會被報告為錯誤。所有其它 pragma 的處理方式取決於編譯常量 BOOST_WAVE_RETURN_PRAGMA_DIRECTIVES,該常量可以指定這些 pragma 是否按原樣保留在輸出流中。請注意,operator _Pragma 變體總是會在對其 pragma 被求值之前得到完全的預處理。#pragma 變體則只是在 BOOST_WAVE_PREPROCESS_PRAGMA_BODY 編譯常量在編譯時有被指定的情況下才會進行預處理。有關可用編譯常量的更多信息,請見這裡

It is fairly easy to implement your own #pragma wave ... directives. All you have to do is to implement your own interpret_pragma preprocessing hook function (see here) 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 interpret_pragma function (for instance the #pragma wave timer() directive).
要實現你自己的 #pragma wave ... 指令相當容易。你要做的就是,實現你自己的 interpret_pragma 預處理鉤子函數(見),該函數用於處理新增的指令。作為一個例子,你可以看一下 Wave 驅動器程序,它提供了一個 interpret_pragma 函數,實現了以上所有列出的 pragma (例如 #pragma wave timer() 指令)。