| The Context Policy (depreciated interface) | |
 |
 |
 |
Introduction
Header 'wave/preprocessing_hooks.hpp' synopsis
Member functions
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
This policy type is used as a template parameter to the boost::wave::context<> object, where the default policy provides empty hook functions only.
namespace boost { namespace wave { namespace context_policies { struct default_preprocessing_hooks { // general hook functions template <typename TokenT> void found_directive(TokenT const &directive);
// test, whether a given token may be skipped
template <typename ContextT> bool may_skip_whitespace (ContextT const& ctx, TokenT &token, bool &skipped_newline);
// Conditional compilation template <typename ContainerT>
bool evaluated_conditional_expression(ContainerT const& expression,
bool expression_value);
template <typename TokenT> void skipped_token(TokenT const& token);
// macro expansion tracing template <typename TokenT, typename ContainerT> void expanding_function_like_macro(TokenT const ¯odef, std::vector<TokenT> const &formal_args, ContainerT const &definition, TokenT const ¯ocall, std::vector<ContainerT> const &arguments); template <typename TokenT, typename ContainerT> void expanding_object_like_macro(TokenT const ¯o, ContainerT const &definition, TokenT const ¯ocall); template <typename ContainerT> void expanded_macro(ContainerT const &result); template <typename ContainerT> void rescanned_macro(ContainerT const &result); // include file tracing functions void found_include_directive(std::string const &filename, bool include_next); void opened_include_file(std::string const &relname, std::string const& absname, std::size_t include_depth, bool is_system_include); void returning_from_include_file(); // interpretation of #pragma's of the form // 'wave option[(value)]' template <typename ContextT, typename ContainerT> bool interpret_pragma(ContextT const &ctx, ContainerT &pending, typename ContextT::token_type const &option, ContainerT const &values, typename ContextT::token_type const &pragma_token); // macro definition hooks template < typename TokenT, typename ParametersT, typename DefinitionT > void defined_macro(TokenT const &name, bool is_functionlike, ParametersT const ¶meters, DefinitionT const &definition, bool is_predefined); template <typename TokenT> void undefined_macro(TokenTconst &name); }; }}} // namespace boost::wave::context_policies
template <typename TokenT> void found_directive(TokenT const &directive);
The function found_directive is called, whenever the preprocessor has detected one of the preprocessing directives (#define, #undef, #if, #idef, #ifndef, #elif, #endif, #error, #include, #pragma or #warning) .
The parameter directive refers to the token containing the detected preprocessing directive.
template <typename ContextT, typename TokenT> bool may_skip_whitespace(ContextT const& ctx, TokenT &token, bool& skipped_newline);
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.
evaluated_conditional_expression
template <typename ContainerT>
void evaluated_conditional_expression( ContainerT const& expression, bool expression_value);
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 holds the non-expanded token sequence comprising the evaluated expression.
The parameter expression_value contains the result of the evaluation of the expression in the current preprocessing context.
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 parameter token refers to the token to be skipped.
template <typename TokenT, typename ContainerT> void expanding_function_like_macro(TokenT const ¯odef, std::vector<TokenT> const &formal_args, ContainerT const &definition, TokenT const ¯ocall, std::vector<ContainerT> const &arguments);
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.
template <typename TokenT, typename ContainerT> void expanding_object_like_macro(TokenT const ¯o, ContainerT const &definition, TokenT const ¯ocall);
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.
template <typename ContainerT> void expanded_macro(ContainerT const &result);
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.
template <typename ContainerT> void rescanned_macro(ContainerT const &result);
The function rescanned_macro is called whenever the rescanning of a macro is finished, i.e. the macro expansion is complete.
The parameter result contains the the result of the whole macro expansion. This is a standard STL container containing the generated token sequence.
void found_include_directive(std::string const &filename, bool include_next);
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.
void opened_include_file(std::string const &rel_filename, std::string const &abs_filename, std::size_t include_depth, bool is_system_include);
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.
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.
template <typename ContextT, typename ContainerT> bool interpret_pragma(ContextT const &ctx, ContainerT &pending, typename ContextT::token_type const &option, ContainerT const &values, typename ContextT::token_type const &pragma_token);
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.
template < typename TokenT, typename ParametersT, typename DefinitionT > void defined_macro(TokenT const &name, bool is_functionlike, ParametersT const ¶meters, DefinitionT const &definition, bool is_predefined);
The function defined_macro is called whenever a macro was defined successfully.
The parameter name is a reference to the token holding the macro name.
The parameter is_functionlike is set to true whenever the newly defined macro is defined as a function like macro.
The parameter parameters holds the parameter tokens for the macro definition. If the macro has no parameters or if it is a object like macro, then this container is empty.
The parameter definition contains the token sequence given as the replacement sequence (definition part) of the newly defined macro.
The parameter is_predefined is set to true for all macros predefined during the initialisation pahase of the library.
template <typename TokenT> void undefined_macro(TokenTconst &name);
The function undefined_macro is called whenever a macro definition was removed successfully.
The parameter name holds the token of the macro which definition was removed.
|
|
|
Copyright © 2003-2011 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: Tuesday, May 23, 2006 12:52