The Tracing Policy

Introduction
Header 'wave/macro_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/macro_trace_policies.hpp synopsis

namespace wave {
namespace macro_trace_policies {
 
    struct tracing_policy {

        // general control function
        void enable_tracing(bool enable);
 
        // 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);
};

}   // namespace macro_trace_policy
}   // namespace wave

Member functions

General control functions

enable_tracing

    void enable_tracing(bool 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 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.

Copyright © 2003 Hartmut Kaiser

Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.