Introduction

Please note that the following description relates to a depreciated interface as it was used by default up to Boost V1.34.x. For the new interface please refer to The Context Policy. You can still force to use this older interface by defining the BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS preprocessing constant as outlined in the Compile
Time Configuration section. By default the new interface is used starting Boost V1.35.0, while the older one is used by default otherwise.

The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever

a preprocessor directive has been recognized,

a token is about to be returned from the preprocessor,

a macro get's defined or undefined,

a macro has been expanded or rescanned,

an include file has been opened or left,

a conditional expression was evaluated,

a token has to be skipped because it is contained in a non-evaluated conditional block,

a pragma of the form 'wave option[(value)]' has been recognised.

This policy type is used as a template parameter to the boost::wave::context<>
object, where the default policy provides empty hook functions only.

The function may_skipwhitespace will be called by the library, whenever a token is about to be returned to the calling application.

The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Wave V1.2.4 release.

The token parameter holds a reference to the current token. The policy is free to change this token if needed.

The skipped_newline parameter holds a reference to a boolean value which should be set to true by the policy function whenever a newline is going to be skipped.

If the return value is true, the given token is skipped and the preprocessing continues to the next token. If the return value is false, the given token is returned to the calling application. Caution has to be used, because by returning true the policy function is able to force skipping even significant tokens not only whitespace.

Conditional compilation hook functions

The function evaluated_conditional_expression is called, whenever the preprocessor has encountered a #if, #elif, #ifdef or #ifndef directive. This hook gets passed the non-expanded conditional expression (as it was given in the analysed source file) and the result of the evaluation of this expression in the current preprocessing context.

The parameter expression_value contains the result of the evaluation of
the expression in the current preprocessing context.

skipped_token

template <typename TokenT>
void skipped_token(TokenT const& token);

The function skipped_token is called, whenever a token is about to be skipped due to a false preprocessor condition (code fragments to be
skipped inside the not evaluated conditional #if/#else/#endif branches).

The function expanding_function_like_macro is called, whenever a
function-like macro is to be expanded, i.e. before the actual expansion
starts.

The macroname 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.

The formal_args parameter holds the formal arguments used during
the definition of the macro.

The definition 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.

The macrocall parameter marks the position where this macro is invoked.
It contains the token, which identifies the macro call inside the preprocessed
input stream.

The arguments 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.

The function expanding_object_like_macro is called, whenever a object-like
macro is to be expanded, i.e. before the actual expansion starts.

The macroname 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.

The definition 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.

The macrocall parameter marks the position where this macro is invoked.
It contains the token which identifies the macro call inside the preprocessed
input stream.

The function expanded_macro 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 before
the rescanning process starts.

The parameter result contains the the result of the macro expansion
so far. This is a standard STL container containing the generated token sequence.

Include file tracing functions

The function found_include_directive is called whenever whenever a #include directive was located..

The parameter filename contains the (expanded) file name found after
the #include directive. This has the format <file>, "file" or
file.
The formats <file> or "file" are used for #include directives found
in the preprocessed token stream, the format file is used for files
specified through the --force_include command line argument.

The parameter include_next is set to true if the found directive was
a #include_next directive and the BOOST_WAVE_SUPPORT_INCLUDE_NEXT preprocessing constant was defined to something != 0.

The function opened_include_file is called whenever a file referred
by an #include directive was successfully located and opened.

The parameter rel_filename contains the (normalised) probably relative file system path of the opened file. The concrete format of this file name depends on the format of the include search path given to the library beforehand.

The parameter abs_filename contains the (normalised) full file system path of the
opened file.

The include_depth parameter contains the current include file depth.

The is_system_include parameter denotes, if the given file was found
as a result of a #include <...> directive.

returning_from_include_file

void returning_from_include_file();

The function returning_from_include_file is called whenever an
included file is about to be closed after it's processing is complete.

The function interpret_pragma is called whenever an unrecognized
#pragma wave ... or operator _Pragma("wave ...")
is found in the input stream.

The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user.

The pending parameter may be used to push tokens back into the input
stream which are to be used as the replacement text for the whole #pragma wave()
directive. If this sequence is left empty, no replacement takes place, i.e.
the interpreted directive is removed from the generated token stream.

The option parameter contains the name of the interpreted pragma.

The values parameter holds the value of the parameter provided to
the pragma operator.

The pragma_token parameter contains the actual #pragma token which
may be used for extraction of the location information for some error output.

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.