| - | The - Context Object | -![]() |
- ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| + | The Context Object | +![]() |
+
![]() |
- ![]() |
--Introduction
-
- Header 'wave/context.hpp' synopsis
- Public Typedefs
- Template parameters
- Member functions
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 { - - template < - typename Iterator, typename LexIterator, - typename InputPolicy, typename ContextPolicy - > - 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>", - ContextPolicy const& ctx_policy = ContextPolicy()) - - // 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); - template <typename String> - bool is_defined_macro(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> ¶meters, - token_sequence_type &definition) const; - name_iterator macro_names_begin(); - name_iterator macro_names_end(); - const_name_iterator macro_names_begin() const; - const_name_iterator macro_names_end() 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
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. |
-
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. |
-
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.
-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. |
-
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).
-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.
- -iterator_type begin();
-+Initializes and returns the starting iterator for the preprocessed token - stream.
- +Introduction
+
+ Header + 'wave/context.hpp' synopsis
+ Public + Typedefs
+ Template + parameters
+ Member + functions
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;
// constructor
context(Iterator const &first_,
Iterator const &last_,
char const *fname = "<Unknown>",
ContextPolicy const& ctx_policy = ContextPolicy())
// iterator interface
iterator_type begin() const;
iterator_type begin(Iterator const &first,
Iterator const &last) 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
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;
// 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
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. |
+
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.
+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. |
+
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).
+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.
+ +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.
iterator_type end() const;
--Initializes and returns the end of stream iterator to compare with for detecting - the end of the preprocessed token stream.
++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.
+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.
-
bool add_include_path(char const *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.
++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.
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 +
+-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.
+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.
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.
+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.
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.
++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
-bool add_macro_definition( - std::string macrostring, - bool is_predefined); +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+-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 definitionThe 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.
+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.
template <typename String> - bool is_defined_macro(String const &name) const;+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.
-Returns, if a macro with the given name is defined, i.e. if it is contained in the macro symbol table.
+ -bool get_macro_definition( - std::string const &name, bool &is_function_style, - bool &is_predefined, position_type &pos, - std::vector<token_type> ¶meters, - token_sequence_type &definition) const;+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.
+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.
bool remove_macro_definition( - std::string const &name, - bool even_predefined);+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.
+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.
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.
+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; +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.
+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 + information
get_version
-static std::string 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.
+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.
+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
-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, - 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) .
+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 = 0xFF80,
// additional fine tuning of the general behavior
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_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.
+- 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.
+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
...
#endifNote, 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 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.
+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_depthvoid 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).
+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
+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) -
- 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, December 2, 2007 19:12 - -
+Last + updated: + Sunday, October 12, 2008 20:14 +
diff --git a/doc/class_reference_ctxpolicy.html b/doc/class_reference_ctxpolicy.html index 879794d..836fa48 100644 --- a/doc/class_reference_ctxpolicy.html +++ b/doc/class_reference_ctxpolicy.html @@ -5,33 +5,39 @@ - -
-
- +- The - Context Policy (new, upcoming interface) -- + +
+ ++ The + Context Policy ++
-
-- + +- - - - + ++ + + + +Introduction
Header 'wave/preprocessing_hooks.hpp' synopsis
Member functionsIntroduction
-Please note that the following description relates to the new preprocessing hooks interface used by default starting with the Boost V1.35.0 release. If you are interested in the older interface please look here.
+Please note that the following description relates to the new + preprocessing hooks interface used by default starting with the Boost + V1.35.0 release. If you are interested in the older interface please + look here.
The context policy is used to provide callback hooks, which are called from inside the library into the user code, whenever
-
- a preprocessor directive has been recognized,
@@ -43,169 +49,111 @@- a token has to be skipped because it is contained in a non-evaluated conditional block,
- a pragma of the form 'wave option[(value)]' has been recognized.
This policy type is used as a template parameter to the boost::wave::context<> - object, where the default policy provides empty hook functions only.
-Header wave/preprocessing_hooks.hpp - synopsis
--namespace boost { -namespace wave { -namespace context_policies { - - struct default_preprocessing_hooks { - - // general hook functions - template <typename ContextT, typename TokenT> - bool found_directive(ContextT const &ctx, - TokenT const &directive);+ template <typename ContextT, typename ContainerT>
- // test, whether a given token may be skipped
template <typename ContextT> - bool may_skip_whitespace (ContextT const& ctx, - TokenT &token, bool &skipped_newline);
- // Conditional compilation - template <typename ContextT, typename ContainerT>
bool evaluated_conditional_expression( - ContextT const &ctx, ContainerT const& expression,
bool expression_value);
- template <typename ContextT, typename TokenT> - void skipped_token(ContextT const &ctx, - TokenT const& token);
- // macro expansion tracing +This policy type is used as a template parameter to the boost::wave::context<> object, where the default policy provides empty hook functions only.
+Header wave/preprocessing_hooks.hpp synopsis
+namespace boost {ContextT, typename TokenT, typename ContainerT,
namespace wave {
namespace context_policies {
struct default_preprocessing_hooks {
// general hook functions + template <typename ContextT, typename TokenT>
bool found_directive(ContextT const &ctx,
TokenT const &directive);
template <typename ContextT, typename ExceptionT>
void throw_exception(ContextT const &ctx,
ExceptionT const& e);
// test, whether a given token may be skipped
template <typename ContextT>
bool may_skip_whitespace (ContextT const& ctx,
TokenT &token, bool &skipped_newline);
+ // Conditional compilation + template <
typename ContextT, typename TokenT,
typename ContainerT
>
bool evaluated_conditional_expression(
ContextT const &ctx, TokenT const& directive,
ContainerT const& expression, bool expression_value);
+ template <typename ContextT, typename TokenT>
void skipped_token(ContextT const &ctx,
TokenT const& token);
template <typename ContextT, typename TokenT>
TokenT const& generated_token(ContextT const &ctx,
TokenT const& token);
// macro expansion tracing template < - typename ContextT, typename TokenT, typename ContainerT, - typename IteratorT - > - bool expanding_function_like_macro( - ContextT const &ctx, TokenT const ¯odef, - std::vector<TokenT> const &formal_args, - ContainerT const &definition, TokenT const ¯ocall, - std::vector<ContainerT> const &arguments, - IteratorT const &seqstart, Iterator const &seqend); - - template <typename ContextT, typename TokenT, typename ContainerT> - bool expanding_object_like_macro( - ContextT const &ctx, TokenT const ¯o, - ContainerT const &definition, TokenT const ¯ocall); - - template <typename ContextT, typename ContainerT> - void expanded_macro(ContextT const &ctx, - ContainerT const &result); - - template <typename ContextT, typename ContainerT> - void rescanned_macro(ContextT const &ctx, - ContainerT const &result); - - // include file tracing functions - template <typename ContextT> - bool found_include_directive(ContextT const &ctx, - std::string const &filename, bool include_next); - - template <typename ContextT> - void opened_include_file(ContextT const &ctx, - std::string const &relname, std::string const& absname, - std::size_t include_depth, bool is_system_include); - - template <typename ContextT> - void returning_from_include_file(ContextT const &ctx); - - // interpretation of #pragma's of the form + typename
typename IteratorT
>
bool expanding_function_like_macro(
ContextT const &ctx, TokenT const ¯odef,
std::vector<TokenT> const &formal_args,
ContainerT const &definition, TokenT const ¯ocall,
std::vector<ContainerT> const &arguments,
IteratorT const &seqstart, Iterator const &seqend);
template <typename ContextT, typename TokenT, typename ContainerT>
bool expanding_object_like_macro(
ContextT const &ctx, TokenT const ¯o,
ContainerT const &definition, TokenT const ¯ocall);
template <typename ContextT, typename ContainerT>
void expanded_macro(ContextT const &ctx,
ContainerT const &result);
template <typename ContextT, typename ContainerT>
void rescanned_macro(ContextT const &ctx,
ContainerT const &result);
// include file tracing functions + template <typename ContextT>
bool found_include_directive(ContextT const &ctx,
std::string const &filename, bool include_next);
template <typename ContextT>
void opened_include_file(ContextT const &ctx,
std::string const &relname, std::string const& absname,
bool is_system_include);
template <typename ContextT>
void returning_from_include_file(ContextT const &ctx);
// 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 ContextT, typename TokenT, - typename ParametersT, typename DefinitionT - > - void defined_macro(ContextT const &ctx, TokenT const &name, - bool is_functionlike, ParametersT const ¶meters, - DefinitionT const &definition, bool is_predefined); - - template <typename ContextT, typename TokenT> - void undefined_macro(ContextT const &ctx, - TokenT const &name); - - // #error and #warning directive hooks - template <typename ContextT, typename ContainerT> - bool found_warning_directive(ContextT const &ctx, - ContainerT const &message); - - template <typename ContextT, typename ContainerT> - bool found_error_directive(ContextT const &ctx, - ContainerT const &message); - - // #line directive hook - template <typename ContextT, typename ContainerT> - void found_line_directive(ContextT const &ctx, - ContainerT const &arguments, unsigned int line, - std::string const& filename); - }; - -}}} // namespace boost::wave::context_policies
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 ContextT, typename TokenT, + typename ParametersT, typename DefinitionT
>
void defined_macro(ContextT const &ctx, TokenT const &name, + bool is_functionlike, ParametersT const ¶meters,
DefinitionT const &definition, bool is_predefined);
template <typename ContextT, typename TokenT>
void undefined_macro(ContextT const &ctx,
TokenT const &name);
// #error and #warning directive hooks + template <typename ContextT, typename ContainerT>
bool found_warning_directive(ContextT const &ctx,
ContainerT const &message);
template <typename ContextT, typename ContainerT>
bool found_error_directive(ContextT const &ctx,
ContainerT const &message);
// #line directive hook + template <typename ContextT, typename ContainerT>
void found_line_directive(ContextT const &ctx,
ContainerT const &arguments, unsigned int line,
std::string const& filename);
};
}}} // namespace boost::wave::context_policiesMember functions
General hook functions
-template <typename ContextT, typename TokenT> - bool found_directive(ContextT const& ctx, TokenT const &directive); +template <typename ContextT, typename TokenT>
bool found_directive(ContextT const& ctx, TokenT const &directive);
+ +The function found_directive is called, whenever the preprocessor has detected one of the preprocessing directives (#define, #undef, #if, #idef, #ifndef, #elif, #endif, #error, #include, #pragma or #warning) .
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
The parameter directive refers to the token containing the detected preprocessing directive.
-If the return value is true, the directive will be skipped altogether, i.e. no preprocessing is done. The overall directive is replaced by a single newline character. If the return value is false, the directive is processed in the normal manner.
+If the return value is true, the directive will be + skipped altogether, i.e. no preprocessing is done. The overall + directive is replaced by a single newline character. If the return + value is false, the directive is processed in the normal manner.
+template <typename ContextT, typename ExceptionT>+
void throw_exception(ContextT const &ctx,
ExceptionT const& e);+-he function throw_exception is called, whenever a preprocessing exception occurs .
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user.
+The parameter e is the exception object containing detailed error information.
template <typename ContextT, typename TokenT> - bool may_skip_whitespace(ContextT const& ctx, TokenT &token, - bool& skipped_newline); +template <typename ContextT, typename TokenT>
bool may_skip_whitespace(ContextT const& ctx, TokenT &token,
bool& skipped_newline);
The function may_skipwhitespace will be called by the library, whenever a token is about to be returned to the calling application.
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Wave V1.2.4 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Wave V1.2.4 release.
The token parameter holds a reference to the current token. The policy is free to change this token if needed.
-The skipped_newline parameter holds a reference to a boolean value which should be set to true by the policy function whenever a newline is going to be skipped.
+The skipped_newline parameter holds a reference to a + boolean value which should be set to true by the policy function + whenever a newline is going to be skipped.
If the return value is true, the given token is skipped and the preprocessing continues to the next token. If the return value is false, the given token is returned to the calling application. Caution has to be used, because by returning true the policy function is able to force skipping even significant tokens not only whitespace.
Conditional compilation hook functions
evaluated_conditional_expression
-template <typename ContextT, typename ContainerT>
bool evaluated_conditional_expression(ContextT const& ctx, - ContainerT const& expression, bool expression_value); +template <typename ContextT, typename TokenT, typename ContainerT>
bool evaluated_conditional_expression(ContextT const& ctx,
TokenT const& directive, ContainerT const& expression,
bool expression_value);
--The function evaluated_conditional_expression is called, whenever the preprocessor has encountered a #if, #elif, #ifdef or #ifndef directive. This hook gets passed the non-expanded conditional expression (as it was given in the analysed source file) and the result of the evaluation of this expression in the current preprocessing context.
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The function evaluated_conditional_expression is called, whenever the preprocessor has encountered a #if, #elif, #ifdef or #ifndef directive. This hook gets passed the non-expanded conditional + expression (as it was given in the analysed source file) and the result + of the evaluation of this expression in the current preprocessing + context.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
+The token parameter holds a reference to the evaluated directive token.
The parameter expression holds the non-expanded token sequence comprising the evaluated expression.
The parameter expression_value contains the result of the evaluation of the expression in the current preprocessing context.
-The return value defines, whether the given expression has to be evaluated again, allowing to decide which of the conditional branches should be expanded. You need to return 'true' from this hook function to force the expression to be re-evaluated. Note, this was changed from a 'void' for the Boost V1.35.0 release.
+The return value defines, whether the given expression has to be + evaluated again, allowing to decide which of the conditional branches + should be expanded. You need to return 'true' from this hook function to force the expression to be re-evaluated. Note, this was changed from a 'void' for the Boost V1.35.0 release.
template <typename ContextT, typename TokenT> - void skipped_token(ContextT const& ctx, TokenT const& token); +template <typename ContextT, typename TokenT>
void skipped_token(ContextT const& ctx, TokenT const& token);
+ +The function skipped_token is called, whenever a token is about to be skipped due to a false preprocessor condition (code fragments to be - skipped inside the not evaluated conditional #if/#else/#endif branches).
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+ skipped inside the not evaluated conditional #if/#else/#endif branches). +The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
The parameter token refers to the token to be skipped.
template <typename ContextT, typename TokenT>+
TokenT const& generated_token(ContextT const& ctx, TokenT const& token);
++The function generated_token is called, whenever a token is about to be returned from the library.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
+The parameter token refers to the token about to be + returned from the library. This function may alter the token, but in + this case it must be implemented with a non-const reference for the + token parameter, allowing to modify the token in place.
+The default behavior is to return the passed token reference unchanged to the caller.
+Macro expansion tracking functions
-template <typename ContextT, typename TokenT, typename ContainerT> - bool expanding_function_like_macro( - ContextT const& ctx, TokenT const ¯odef, - std::vector<TokenT> const &formal_args, - ContainerT const &definition, TokenT const ¯ocall, - std::vector<ContainerT> const &arguments, - IteratorT const &seqstart, Iterator const &seqend);-+template <typename ContextT, typename TokenT, typename ContainerT>+
bool expanding_function_like_macro(
ContextT const& ctx, TokenT const ¯odef,
std::vector<TokenT> const &formal_args,
ContainerT const &definition, TokenT const ¯ocall,
std::vector<ContainerT> const &arguments,
IteratorT const &seqstart, Iterator const &seqend);-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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
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.
@@ -224,20 +172,21 @@The parameters seqstart and seqend point into the input token stream allowing to access the whole token sequence comprising the macro invocation (starting with the opening parenthesis and ending after the - closing one).
-If the return value is true, the macro is not expanded, i.e. the overall macro invocation sequence, including the parameters are copied to the output without further processing . If the return value is false, the macro is expanded as expected.
+
+ closing one).If the return value is true, the macro is not expanded, + i.e. the overall macro invocation sequence, including the parameters + are copied to the output without further processing . If the return + value is false, the macro is expanded as expected.
template <typename ContextT, typename TokenT, typename ContainerT> - bool expanding_object_like_macro( - ContextT const& ctx, TokenT const ¯o, - ContainerT const &definition, TokenT const ¯ocall); +template <typename ContextT, typename TokenT, typename ContainerT>-
bool expanding_object_like_macro(
ContextT const& ctx, TokenT const ¯o,
ContainerT const &definition, TokenT const ¯ocall);
+-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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
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.
@@ -248,95 +197,88 @@ It contains the token which identifies the macro call inside the preprocessed input stream.If the return value is true, the macro is not expanded, i.e. the macro symbol is copied to the output without further processing. If the return value is false, the macro is expanded as expected.
+
-template <typename ContextT, typename ContainerT> - void expanded_macro(ContextT const& ctx, ContainerT const &result); +template <typename ContextT, typename ContainerT>-
void expanded_macro(ContextT const& ctx, 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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+ macros herein are replaced by its corresponding expansion results, but before the rescanning process starts. +The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
The parameter result contains the the result of the macro expansion so far. This is a standard STL container containing the generated token sequence.
template <typename ContextT, typename ContainerT> - void rescanned_macro(ContextT const& ctx, ContainerT const &result); +template <typename ContextT, typename ContainerT>-
void rescanned_macro(ContextT const& ctx, 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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
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
-template <typename ContextT> - bool found_include_directive(ContextT const& ctx, - std::string const &filename, bool include_next); +template <typename ContextT>
bool found_include_directive(ContextT const& ctx,
std::string const &filename, bool include_next);
-The function found_include_directive is called whenever whenever a #include directive was located..
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
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 + 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.
-If the return value is true, the include directive is not executed, i.e. the file to include is not loaded nor processed. The overall directive is replaced by a single newline character. If the return value is false, the directive is executed in a normal manner.
+
+ a #include_next directive and the BOOST_WAVE_SUPPORT_INCLUDE_NEXT preprocessing constant was defined to something != 0.If the return value is true, the include directive is not + executed, i.e. the file to include is not loaded nor processed. The + overall directive is replaced by a single newline character. If the + return value is false, the directive is executed in a normal manner.
template <typename ContextT> - void opened_include_file(ContextT const& ctx, - std::string const &rel_filename, std::string const &abs_filename, - std::size_t include_depth, bool is_system_include); +template <typename ContextT>-
void opened_include_file(ContextT const& ctx,
std::string const &rel_filename, std::string const &abs_filename,
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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
-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 ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
+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. -
+ opened file.The is_system_include parameter denotes, if the given file was found as a result of a #include <...> directive.
template <typename ContextT> - void returning_from_include_file(ContextT const& ctx); +template <typename ContextT>-
void returning_from_include_file(ContextT const& ctx);
+The function returning_from_include_file is called whenever an included file is about to be closed after it's processing is complete.
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
Interpretation of #pragma's
-template <typename ContextT, 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); +template <typename ContextT, 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);
-The function interpret_pragma is called whenever an unrecognized - #pragma wave ... or operator _Pragma("wave ...") - is found in the input stream.
++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. + 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 @@ -350,92 +292,87 @@
Macro definition
-template < - typename ContextT, typename TokenT, typename ParametersT, - typename DefinitionT - > - void defined_macro(ContextT const& ctx, - TokenT const &name, bool is_functionlike, - ParametersT const ¶meters, DefinitionT const &definition, - bool is_predefined); +template <-
typename ContextT, typename TokenT, typename ParametersT, + typename DefinitionT
>
void defined_macro(ContextT const& ctx,
TokenT const &name, bool is_functionlike,
ParametersT const ¶meters, DefinitionT const &definition,
bool is_predefined);
The function defined_macro is called whenever a macro was defined successfully.
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
++-The function defined_macro is called whenever a macro was defined successfully.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
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.
+ 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.
+ 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.
+ during the initialisation pahase of the library.
template <typename ContextT, typename TokenT> - void undefined_macro(ContextT const& ctx, TokenT const &name); +template <typename ContextT, typename TokenT>
void undefined_macro(ContextT const& ctx, TokenT const &name);
-The function undefined_macro is called whenever a macro definition was removed successfully.
-The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. Note, this parameter was added for the Boost V1.35.0 release.
+The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user. + Note, this parameter was added for the Boost V1.35.0 release.
The parameter name holds the token of the macro which definition was removed.
template <typename ContextT, typename ContainerT> - bool found_warning_directive(ContextT const& ctx, - ContainerT const &message); +template <typename ContextT, typename ContainerT>
bool found_warning_directive(ContextT const& ctx,
ContainerT const &message);
--The function found_warning_directive is called whenever a #warning directive has been encountered. Note, this function was added for the Boost V1.35.0 release. This function will be called only if the BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE compile time constant was defined to something not equal to zero (see the Compile Time Configuration for more information).
+The function found_warning_directive is called whenever a #warning directive + has been encountered. Note, this function was added for the Boost + V1.35.0 release. This function will be called only if the BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE compile time constant was defined to something not equal to zero (see the Compile Time Configuration for more information).
The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user.
The parameter message references the argument token sequence of the encountered #warning directive.
If the return value is false, the library throws a preprocessor - exception of the type
+ exception of the typewarning_directive(normal execution continues), if the return value is true the execution continues as if no #warning directive has been found and the overall directive is replaced by a single newline.warning_directive(normal execution continues), if the return value is true the execution continues as if no #warning directive has been found and the overall directive is replaced by a single newline.template <typename ContextT, typename ContainerT> - bool found_error_directive(ContextT const& ctx, - ContainerT const &message); +template <typename ContextT, typename ContainerT>
bool found_error_directive(ContextT const& ctx,
ContainerT const &message);
-The function found_error_directive is called whenever a #error directive has been encountered. Note, this function was added for the Boost V1.35.0 release.
The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user.
The parameter message references the argument token sequence of the encountered #error directive.
If the return value is false, the library throws a preprocessor - exception of the type
+ exception of the typeerror_directive(normal execution continues), if the return value is true the execution continues as if no #error directive has been found and the overall directive is replaced by a single newline.error_directive(normal execution continues), if the return value is true the execution continues as if no #error directive has been found and the overall directive is replaced by a single newline.template <typename ContextT, typename ContainerT> - void found_line_drective(ContextT const& ctx, - ContainerT const &arguments, unsigned int line, - std::string const& filename); +template <typename ContextT, typename ContainerT>
void found_line_drective(ContextT const& ctx,
ContainerT const &arguments, unsigned int line,
std::string const& filename);
The function found_line_directive is called whenever a #line directive has been encountered. Note, this function was added for the Boost V1.35.0 release.
The ctx parameter provides a reference to the context_type used during instantiation of the preprocessing iterators by the user.
The parameter arguments references the argument token sequence of the encountered #line directive.
-The parameter line contains the recognized line number from the #line directive.
-The parameter filename references the recognized file name from the #line directive (if there was one given).
+The parameter line contains the recognized line number from the #line directive.
+The parameter filename references the recognized file name from the #line directive (if there was one given).
-
- + +- - - - + ++ + + +
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: - Sunday, December 2, 2007 19:12 -
+ 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, October 12, 2008 20:13 +