The Tracing Policy

Introduction
Header 'wave/trace_policies.hpp' synopsis
Member functions

Introduction

There is implemented an unique tracing facility as a part of the Wave library, which allows to selectively trace all stages of the macro expansion process, involving the argument expansion and the rescanning of the replacement results. This tracing facility greatly helps to understand foreign code or to debug your own macros.

The tracing policy is used to trace the macro expansion of macros whenever it is requested from inside the input stream to preprocess through the #pragma wave_option(trace: enable) (or _Pragma("wave trace(enable)")) directive. The macro tracing may be disabled again with the help of a #pragma wave_option(trace: disable) (or _Pragma("wave trace(disable)")) directive. Note though, that the Wave driver executable requires additionally to specify the -t (--trace) command line option, which defines the stream, where the trace output goes.

This policy type is used as a template parameter to the wave::context<> object, where the default policy does no tracing at all.

Header wave/trace_policies.hpp synopsis


namespace wave {
namespace trace_policies {
 
    enum trace_flags {
	        trace_nothing = 0,      // disable tracing
			trace_macros = 1,       // enable macro tracing
	        trace_includes = 2      // enable include file tracing
    };

    struct default_tracing {

        // general control function
        void enable_tracing(trace_flags enable);
        trace_flags tracing_enabled();

        // macro tracing functions
        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 opened_include_file(std::string const &filename, 
            std::size_t include_depth, bool is_system_include); 

        void returning_from_include_file();

        // interpretation of unknown #pragma's
        template <typename TokenT, typename ContainerT>
		        bool interpret_pragma(ContainerT &pending, 
             TokenT const &option, ContainerT const &values, 
             TokenT const &pragma_token, 
	            wave::language_support language);
    };

}   // namespace macro_trace_policy
}   // namespace wave

Member functions

General control functions

enable_tracing

    void enable_tracing(trace_flags enable);

The function enable_tracing is called, whenever the status of the tracing was changed from inside the stream to preprocess.

The parameter enable is to be used as the new tracing status.

tracing_enabled

    trace_flags tracing_enabled();

The function tracing_enabled should return the current tracing status.

Tracing functions

Macro tracing 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 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 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

opened_include_file

    void opened_include_file(std::string const &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 filename contains the 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.

interpret_pragma

    template <typename TokenT, typename ContainerT>
		   bool interpret_pragma(ContainerT &pending, 
        TokenT const &option, ContainerT const &values, 
        TokenT const &pragma_token, 
        wave::language_support language);

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

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.

The language parameter contains the current language mode, in which the Wave library operates.

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.


Last updated: Monday, January 5, 2004 14:57