#

The Context Policy

> Introduction
> Header 'wave/preprocessing_hooks.hpp' synopsis
> Member functions

## Introduction

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.

## Header wave/preprocessing_hooks.hpp synopsis

    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>
            void 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 &macrodef,
                std::vector<TokenT> const &formal_args,
                ContainerT const &definition, TokenT const &macrocall,
                std::vector<ContainerT> const &arguments);

            template <typename TokenT, typename ContainerT>
            void expanding_object_like_macro(TokenT const &macro,
                ContainerT const &definition, TokenT const &macrocall);

            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 &parameters, DefinitionT const &definition,
                bool is_predefined);

            template <typename TokenT>
            void undefined_macro(TokenTconst &name);
        };

    }}}   // namespace boost::wave::context_policies

## Member functions

### General hook functions

found_directive

        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.

may_skipwhitespace

        template <typename ContextT>
        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 after the Boost V1.34.0 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

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.

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 parameter `token` refers to the token to be skipped.

### Macro expansion tracking functions

expanding_function_like_macro

        template <typename TokenT, typename ContainerT>
        void expanding_function_like_macro(TokenT const &macrodef,
            std::vector<TokenT> const &formal_args,
            ContainerT const &definition, TokenT const &macrocall,
            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.

expanding_object_like_macro

        template <typename TokenT, typename ContainerT>
        void expanding_object_like_macro(TokenT const &macro,
            ContainerT const &definition, TokenT const &macrocall);

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

expanded_macro

        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.

rescanned_macro

        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.

### Include file tracing functions

found_include_directive

        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.

opened_include_file

        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.

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.

### Interpretation of #pragma's

interpret_pragma

        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.

### Macro definition

defined_macro

        template <
            typename TokenT, typename ParametersT, typename DefinitionT
        >
        void defined_macro(TokenT const &name, bool is_functionlike,
            ParametersT const &parameters, 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.

undefined_macro

        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-2007 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, February 26, 2006 14:19