The Context Policy

#  | 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 macro get's defined or undefind,
- a macro is expanded or rescanned,
- an include file is opened or left,
- a pragma of the form `'wave option[(value)]'` is recognised.

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

## Header wave/preprocessing_hooks.hpp synopsis

    namespace boost {
    namespace wave {
    namespace context_policies {

        struct default_preprocessing_hooks {

            // general control function
            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

### 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 Context, 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-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