|
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.
namespace boost { namespace wave { struct this_type {};
template < typename Iterator, typename LexIterator, typename InputPolicy, typename ContextPolicy, typename Derived = this_type > class context : public InputPolicy { typedef <unspecified> token_sequence_type;
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;
context(Iterator const &first_, Iterator const &last_, char const *fname = "<Unknown>", ContextPolicy const& ctx_policy = ContextPolicy())
iterator_type begin() const; iterator_type begin(Iterator const &first, Iterator const &last) const; iterator_type end() const;
bool add_include_path(char const *path_); bool add_sysinclude_path(char const *path_); void set_sysinclude_delimiter(); size_t get_iteration_depth() const;
template <typename String> bool add_macro_definition(String macrostring, bool is_predefined = false); template <typename String> bool add_macro_definition(StringT const &name, position_type const& pos, bool has_params, std::vector<token_type> ¶meters, token_sequence_type &definition, bool is_predefined = false)
template <typename String> bool is_defined_macro(String const &name) const; template <typename String> bool remove_macro_definition(String const &name, bool even_predefined = false); void reset_macro_definitions(); template <typename String> bool get_macro_definition( String const &name, bool &is_function_style, bool &is_predefined, position_type &pos, std::vector<token_type> ¶meters, token_sequence_type &definition) const;
typedef <unspecified> macromap_type; typedef typename macromap_type::name_iterator name_iterator; typedef typename macromap_type::const_name_iterator const_name_iterator;
name_iterator macro_names_begin(); name_iterator macro_names_end(); const_name_iterator macro_names_begin() const; const_name_iterator macro_names_end() const;
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;
static std::string get_version(); static std::string get_version_string(); };
} }
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. |
ContextPolicy |
The type of the context policy class, which allows to
customize different aspects of the behaviour of the preprocessing. The
requirements of this policy and the available customization points
provided by this policy are described here.
|
Derived |
The type of the type being derived from the context type (if
any). This template parameter is optional and defaults to 'this_type',
which means that the context type will be used assuming no derived type exists.
|
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 ContextPolicy is omitted, the boost::wave::context_policies::eat_whitespace policy type is used, implementing certain basic preprocessing hooks
needed for normal (default) execution. For further information about
the context 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. |
context_policy_type |
The ContextPolicy 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, ContextPolicy const& ctx_policy);
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 ctx_policy parameter isn't supplied it defaults to a default
constructed ContextPolicy 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(); iterator_type begin(Iterator const &first, Iterator const &last, );
Initializes and returns the starting iterator for the
preprocessed token stream. The iterator pair given by the parameters [first, last) specifies the input sequence to preprocess. The first version of this
function uses the iinput stream as specified by the constructor.
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
template <typename String> bool is_defined_macro(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
template <typename String> bool get_macro_definition( String const &name, bool &is_function_style, bool &is_predefined, position_type &pos, std::vector<token_type> ¶meters, 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
template <typename String> bool remove_macro_definition( 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.
macro_names_begin,
macro_names_end
name_iterator macro_names_begin(); name_iterator macro_names_end(); const_name_iterator macro_names_begin() const; const_name_iterator macro_names_end() const;
The macro_names_begin and macro_names_end functions return iterators allowing to iterate on the names of all
defined macros.
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_normal = 0x01, support_cpp = support_normal,
support_option_long_long = 0x02, support_option_variadics = 0x04, support_c99 = support_option_variadics | support_option_long_long | 0x08,
support_option_mask = 0xFF80,
support_option_insert_whitespace = 0x0080, 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, support_option_emit_pragma_directives = 0x8000 };
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_insert_whitespace flag is set, the Wave library inserts
additional whitespace between tokens where the concatenated string
representation of the two tokens would form another valid C++ token.
This is very importatnt to avoid mis-interpretations of the generated
output if it is going to be processed by a C++ compiler afterwards.
- 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 support_option_emit_pragma_directives flag is set, the Wave library will emit all
unknown #pragma directives to the output. This suport option will be recognized only if
the BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES is defined
during compilation to a value not equal to zero (see here for more
information).
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-2008
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, July 29, 2008 20:30
|