#

The Context Object

> Introduction
> Header 'wave/context.hpp' synopsis
> Public Typedefs
> Template parameters
> Member functions

## Introduction

The `boost::wave::context<>` object is the main user visible object of the `Wave` library. It exists to generate the pair of iterators, which while dereferenced return the preprocessed tokens. Additionally it is used to control other aspects of the preprocessing, such as

> include search paths, which define, where to search for files to be included with `#include <...>` and `#include "..."` directives
> which macros to predefine and which of the predefined macros to undefine
> several other options as for instance to control, whether to enable several extensions to the C++ Standard (as for instance variadics and placemarkers) or not.

## Header wave/cpp_context.hpp synopsis

    namespace boost {
    namespace wave {

        template <
            typename Iterator, typename LexIterator,
            typename InputPolicy, typename TracePolicy
        >
        class context : public InputPolicy
        {
        public:

            typedef pp_iterator<context> iterator_type;
            typedef Token token_type;
            typedef typename token_type::position_type position_type;
            typedef std::list<token_type> token_sequence_type;

        // constructor
            context(Iterator const &first_,
                Iterator const &last_,
                char const *fname = "<Unknown>",
                TracePolicy const& trace = TracePolicy())

        // iterator interface
            iterator_type begin() const;
            iterator_type end() const;

        // maintain include paths
            bool add_include_path(char const *path_);
            bool add_sysinclude_path(char const *path_);
            void set_sysinclude_delimiter();

            size_t get_iteration_depth() const;

        // maintain defined macros
            bool add_macro_definition(std::string macrostring,
                bool is_predefined = false);
            bool is_defined_macro(std::string const &name) const;
            bool remove_macro_definition(std::string const &name,
                bool even_predefined = false);
            void reset_macro_definitions();
            bool get_macro_definition(
                std::string const &name, bool &is_function_style,
                bool &is_predefined, position_type &pos,
                std::vector<token_type> &parameters,
                token_sequence_type &definition) const;

        // other options
            void set_language(language_support enable);
            language_support get_language() const;

            void set_max_include_nesting_depth(std::size_t new_depth);
            size_t get_max_include_nesting_depth() const;

        // get the Wave version information
            static std::string get_version();
            static std::string get_version_string();
        };

    }   // namespace wave
    }   // namespace boost

## Template parameters

The `boost::wave::context` object has three template parameters to specify the concrete behaviour of its operation. The following table describes these with more detail.

Template parameters required for the `boost::wave::context` class
`Iterator` | The type of the underlying iterator, through which the input stream is accessed. This should be at least an `forward_iterator` type iterator.
`LexIterator` | The type of the lexer type to be used by the `Wave` library to identify tokens in the input stream.
`InputPolicy` | The type of the input policy class, which allows to customize the behaviour of the Wave library and the type of the iterators to use, when it comes to including and opening an included file.
`TracePolicy` | The type of the trace policy class, which allows to customize the trace output generated while expanding macros. The requirements for this policy are described here.

For further information about the lexer type to use, please refer to the The Lexer Interface .

If the template parameter `InputPolicy` is omitted, the template `boost::wave::iteration_context_policies::load_file_to_string` is used. For further information about the input policy, please refer to the topic The Input Policy.

If the template parameter TracePolicyT is omitted, the `boost::wave::macro_trace_policies::no_tracing` policy type is used, i.e. by default there is no tracing performed. For further information about the hooking policy, please refer to the topic The Context Policy.

## Public Typedefs

The `boost::wave::context` template defines the following public typedefs, which may be useful while using this class:

Public typedef's defined by the `boost::wave::context` class
`iterator_type` | The `Iterator` template parameter provided, while the `context` class was instantiated.
`lex_type` | The `LexIterator` template parameter provided, while the `context` class was instantiated.
`token_type` | The token type, which is returned by the `context` generated iterators. This type is taken from the `LexIterator` template parameter provided, whicle the `context` class was instantiated.
`input_policy_type` | The `InputPolicy` template parameter provided, while the `context` class was instantiated.
`trace_policy_type` | The `TracePolicy` template parameter provided, while the `context` class was instantiated.
`position_type` | The type of the position information contained in every returned token, which describes the point, at which the given token was recognised.

## Member functions

Constructor

        context(Iterator const &first,
            Iterator const &last, char const *filename,
            TracePolicy const& trace);

Constructs a context object on top of the input stream given by the pair of auxilliary iterators `[first, last)`. The iterators should be at least `forward_iterator` type iterators. The filename parameter is to be supplied for informational purposes only. This string is used for indicating the token positions inside the input stream, it is not validated against the file system. If the filename parameter is not given it defaults to "<Unknown>". If the trace parameter isn't supplied it defaults to a default constructed `TracePolicy` object.

Additionally the macro symbol table is filled with the predefined macros and the current reference directory is set to the path of the given filename. If this filename does not reference valid file system item, the current reference directory is set to the current system directory. (The current reference directory is the file system path, which is used as the target directory during the processing of `#include "..."` directives).

### Iterator interface

The pair of iterators returned by the `context::begin` and `context::end` functions is the main interface for accessing the preprocessed tokens from the preprocessor engine. While iterating over the given iterator range `[begin, end)` there are returned the preprocessed C++ tokens, which are generated on the fly from the underlying input stream. The returned iterators are conceptually of `forward_iterator` type.

begin

        iterator_type begin();

> Initializes and returns the starting iterator for the preprocessed token stream.

end

        iterator_type end() const;

> Initializes and returns the end of stream iterator to compare with for detecting the end of the preprocessed token stream.

### Maintain include paths

The `Wave` library maintains two separate search paths for include files. A search path for user include files and a search path for system include files. Any directories specified with the add_include_path() function before the function set_sysinclude_delimiter() is called are searched only for the case of `#include "..."` directives, they are not searched for `#include <file>` directives. I.e. these directories are added to the user include search path.

If additional directories are specified with the add_include_path() function after a call to the function set_sysinclude_delimiter(), these directories are searched for all `#include` directives. I.e. these directories are added to the system include search path.

In addition, a call to the function set_sysinclude_delimiter() inhibits the use of the current reference directory as the first search directory for `#include "..."` directives. Therefore, the current reference directory is searched only, if it is requested explicitly with a call to the function add_include_path(".").

Callig both functions, the set_sysinclude_delimiter() and add_include_path(".") allows you to control precisely, which directories are searched before the current one and which are searched after.

These functions are modelled after the command line behaviour implemented by the popular gcc compiler.

add_include_path

        bool add_include_path(char const *path);

> Adds the given file system path to the user include search paths. After a call to the set_sysinclude_delimiter() this function adds the given file system path to the system include search paths. Note though, that the given path is validated against the file system.

> If the given path string does not form a name of a valid file system directory item, the function returns `false`. If the given path was successfully added to the include search paths in question, the function returns `true`.

add_sysinclude_path

        bool add_sysinclude_path(char const *path);

> Adds the given file system path to the system include search paths. This function operates on the system include search path regardless of the mode of operation of the add_include_path(). Note though, that the given path is validated against the file system.

> If the given path string does not form a name of a valid file system directory item, the function returns `false`. If the given path was successfully added to the system include search paths, the function returns `true`.

set_sysinclude_delimiter

        void set_sysinclude_delimiter();

> Switches the mode, how the add_include_path() function operates. By default the given file system path is added to the user include search paths. After calling this function a subsequent call to the add_include_path() adds the given file system path to the system include search paths. Additionally it inhibits the the use of the current reference directory as the first search directory for `#include "..."` directives.

get_iteration_depth

        size_t get_iteration_depth() const;

> Returns the actual include iteration depth, i.e. the current number of include levels to be poped from the include iteration context, before the main (topmost) iteration context is reached.

### Maintain defined macros

add_macro_definition

        bool add_macro_definition(
            std::string macrostring,
            bool is_predefined);

> Adds a new macro definition to the macro symbol table. The parameter `macrostring` should contain the macro to define in the command line format, i.e. something like `MACRO(x)=definition`. The following table describes this format in more detail. The parameter `is_predefined` should be true while defining predefined macros, i.e. macros, which are not undefinable with an `#undef` directive from inside the preprocessed input stream. If this parameter is not given, it defaults to `false`.

> Summary of possible formats for defining macros
> `MACRO` | `define `MACRO` as 1`
> `MACRO=` | `define `MACRO` as nothing (empty)`
> `MACRO=definition` | `define `MACRO` as `definition``
> `MACRO(x)` | `define `MACRO(x)` as 1`
> `MACRO(x)=` | `define `MACRO(x)` as nothing (empty)`
> `MACRO(x)=definition` | `define `MACRO(x)` as `definition``

> The function returns `false`, if the macro to define already was defined and the new definition is equivalent to the existing one, it returns true, if the new macro was successfully added to the macro symbol table.

> If the given macro definition resembles a redefinition and the new macro is not identical to the already defined macro (in the sense defined by the C++ Standard), the function throws a corresponding `preprocess_exception`.

is_defined_macro

        bool is_defined_macro(std::string const &name) const;

> Returns, if a macro with the given `name` is defined, i.e. if it is contained in the macro symbol table.

get_macro_definition

        bool get_macro_definition(
            std::string const &name, bool &is_function_style,
            bool &is_predefined, position_type &pos,
            std::vector<token_type> &parameters,
            token_sequence_type &definition) const;

> Allows to retrieve all information known with regard to a macro definition. The parameter `name` specifies the name of the macro the information should be returned for. The parameters `is_function_style` and `is_predefined` return, whether the macro has been defined as a function style macro or as a predefined macro resp. The parameter `pos` will contain the position the macro was defined at. The parameter `parameters` will contain the names of the parameters the macro was defined with and the parameter `definition` will contain the token sequence for the definition (macro body).

> The function returns `true` is the macro was defined and the requested information has been successfully retrieved, `false` otherwise.

remove_macro_definition

        bool remove_macro_definition(
            std::string const &name,
            bool even_predefined);

> Removes the definition of the macro with the given `name` from the macro symbol table. This operation is equivalent to an `#undef` directive with this `name` executed from within the input stream. If the parameter `even_predefined` is `true`, then the macro is removed from the macro symbol table even, if it is defined as a predefined macro.

> Note though, that the following macros are not undefinable in any case: `__FILE__`, `__LINE__`, `__DATE__`, `__TIME__`, `__cplusplus`, `__STDC__`. If the parameter `even_predefined` is not given, it defaults to `false`.

> The function returns `false`, if the macro to undefine was not defined and returns `true` otherwise.

> If the macro to remove may not be undefined (it is a predefined macro and the parameter `even_predefined` is set to `false` or it is one of the mentioned not undefinable macros above) the function throws a `preprocess_exception`.

reset_macro_definitions

        void reset_macro_definitions();

> Resets the macro symbol table to it's initial state, i.e. undefines all user defined macros and inserts the internal predefined macros as described here.

### Get Version information

get_version

        static std::string get_version();

> Returns a string containing the current Wave version formatted as 0xvvrsbbbb (this is a string representation of the equivalent hexadecimal number), where 'vv' is the version number, 'r' the release number, 's' the subrelease number and 'bbbb' the build number. A possible return value looks like 0x00910454. The returned value is the same as is inserted in the preprocessed token stream, when the predefined macro `__WAVE_VERSION__` is expanded.

get_version_str

        static std::string get_version_str();

> Returns a string containing the current Wave version formatted as "v.rr.ss.bbbb", where 'v' is the version number, 'rr' the release number, 'ss' the subrelease number and 'bbbb' the build number. A possible return value looks like "0.9.1.454". The returned value is the same as it will be inserted in the preprocessed token stream, when the predefined macro `__WAVE_VERSION_STR__` is expanded.

### Control extended options

set_language
get_language

        void set_language(language_support language,
            bool reset_macros = true);
        language_support get_language() const;

> This functions allows to specify the language mode, in which the `Wave` library should work. The possible language modes are defined by the enumerated type `language_support`:

>         enum language_support {
>         // support flags for C++98
>             support_normal = 0x01,
>             support_cpp = support_normal,

>         // support flags for C99
>             support_option_long_long = 0x02,
>             support_option_variadics = 0x04,
>             support_c99 = support_option_variadics |
>                           support_option_long_long |
>                           0x08,

>         // the mask for the main language settings
>             support_option_mask = 0xFF00,

>         // additional fine tuning of the general behavior
>             support_option_preserve_comments = 0x0100,
>             support_option_no_character_validation = 0x0200,
>             support_option_convert_trigraphs = 0x0400,
>             support_option_single_line = 0x0800,
>             support_option_prefer_pp_numbers = 0x1000,
>             support_option_emit_line_directives = 0x2000,
>             support_option_include_guard_detection = 0x4000
>         };

> When used with `support_option_variadics` the support for variadics, placemarkers and the `operator _Pragma()` is enabled in normal C++ mode. When used with the `support_option_long_long` the support for long long suffixes is enabled in C++ mode.

> The `support_c99` switches on the C99 language support, which enables variadics, placemarkers, the `operator _Pragma` and long long suffixes by default. Additionally it disables the C++ specific tokens such as `'->*'`, `'.*'`, `'::'` etc.

> The `support_option_...` values are to be used in conjunction with the main language settings (`support_normal` and `support_c99`) .

> - If the `support_option_preserve_comments` flag is set, the `Wave` library preserves almost all comments in the source code. The only comments not preserved are those contained inside macro definitions. If this flag is not set all comments are replaced by a single space.
> - If the `support_option_no_character_validation` flag is set , the `Wave` library does not validate universal character literals (given in the form of `'u1234'` or `'U12345678'`) to be in the allowed value range. This flag is merely used for internal purposes by the testing framework and will be rarely used by a user of the library.
> - If the `support_option_convert_trigraphs` flag is set, the `Wave` library replaces all occurences of trigraph characters with their non-trigraph character sequence (i.e. `'??='` is replaced by `'#'` etc.) . By default no replacement is performed.
> - If the `support_option_single_line` flag is set, the `Wave` library will now reprot an error if the last line of the processed input is not terminated by a new line. This flag is merely used for internal purposes by the testing framework and will be rarely used by a user of the library.
> - If the `support_option_prefer_pp_numbers` flag is set, the `Wave` library is instructed to correctly identify pp-number's in the input stream. These get recognized into 'normal' number tokens before they get returned to the calling application. The flag is set by default and is used merely for internal purposes and will be rarely reset by a user of the library.
> - If the support_option_emit_line_directives flag is set, the `Wave` library will emit #line directives in the generated token stream, if appropriate. This flag is set by default, to prevent the library from generating #line directives it must be reset explicitely.
> - If the support_option_include_guard_detection flag is set, the `Wave` library will try to automatically identify include guards during the processing of a included file. Files which contained include guards are handled as if they contained a #pragma once, i.e. these files wonn#t be opened twice, even if specified in a second #include statement.

> > During this process the library will recognize two forms of include guards:

> >         #ifndef INCLUDE_GUARD_MACRO
> >         #define INCLUDE_GUARD_MACRO
> >         ...
> >         #endif

> >       or

> >         #if !defined(INCLUDE_GUARD_MACRO)
> >         #define INCLUDE_GUARD_MACRO
> >         ...
> >         #endif

> > Note, that the parenthesis in the second form are optional (i.e. `!defined INCLUDE_GUARD_MACRO` will work as well). The code allows for any whitespace, newline and single '#' tokens before the #if/#ifndef and after the final #endif for the include guard to be recognized.

> > This flag is on by default, so if you do not want the library to automatically reconize include guards you will need to reset this explicitely.

> If the parameter `reset_macros` is true the `set_language` function internally resets the list of defined macros, so please be careful not to call it after you have defined your own macros already.

set_max_include_nesting_depth
get_max_include_nesting_depth

        void set_max_include_nesting_depth(size_t new_depth);
        size_t get_max_include_nesting_depth() const;

> This functions allow to set or to get the maximal possible include file nesting depth supported by the `Wave` library. The initial value for this is determined by the preprocessing constant `WAVE_MAX_INCLUDE_LEVEL_DEPTH` (see here).

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: Tuesday, March 20, 2007 14:04