1 /*=============================================================================
2 Boost.Wave: A Standard compliant C++ preprocessor library
6 Copyright (c) 2001-2009 Hartmut Kaiser. Distributed under the Boost
7 Software License, Version 1.0. (See accompanying file
8 LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9 =============================================================================*/
11 #if !defined(DEFAULT_PREPROCESSING_HOOKS_HPP_INCLUDED)
12 #define DEFAULT_PREPROCESSING_HOOKS_HPP_INCLUDED
14 #include <boost/wave/wave_config.hpp>
17 // this must occur after all of the includes and before any code appears
18 #ifdef BOOST_HAS_ABI_HEADERS
19 #include BOOST_ABI_PREFIX
22 ///////////////////////////////////////////////////////////////////////////////
25 namespace context_policies
{
27 ///////////////////////////////////////////////////////////////////////////////
29 // The default_preprocessing_hooks class is a placeholder for all
30 // preprocessing hooks called from inside the preprocessing engine
32 ///////////////////////////////////////////////////////////////////////////////
33 struct default_preprocessing_hooks
35 ///////////////////////////////////////////////////////////////////////////
37 // The function 'expanding_function_like_macro' is called, whenever a
38 // function-like macro is to be expanded.
40 // The parameter 'macrodef' marks the position, where the macro to expand
43 // The parameter 'formal_args' holds the formal arguments used during the
44 // definition of the macro.
46 // The parameter 'definition' holds the macro definition for the macro to
49 // The parameter 'macro_call' marks the position, where this macro invoked.
51 // The parameter 'arguments' holds the macro arguments used during the
52 // invocation of the macro
54 // The parameters 'seqstart' and 'seqend' point into the input token
55 // stream allowing to access the whole token sequence comprising the macro
56 // invocation (starting with the opening parenthesis and ending after the
59 // The return value defines, whether the corresponding macro will be
60 // expanded (return false) or will be copied to the output (return true).
61 // Note: the whole argument list is copied unchanged to the output as well
62 // without any further processing.
64 ///////////////////////////////////////////////////////////////////////////
66 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
68 template <typename TokenT
, typename ContainerT
>
69 void expanding_function_like_macro(
70 TokenT
const& macrodef
, std::vector
<TokenT
> const& formal_args
,
71 ContainerT
const& definition
,
72 TokenT
const& macrocall
, std::vector
<ContainerT
> const& arguments
)
76 template <typename ContextT
, typename TokenT
, typename ContainerT
, typename IteratorT
>
78 expanding_function_like_macro(ContextT
const& ctx
,
79 TokenT
const& macrodef
, std::vector
<TokenT
> const& formal_args
,
80 ContainerT
const& definition
,
81 TokenT
const& macrocall
, std::vector
<ContainerT
> const& arguments
,
82 IteratorT
const& seqstart
, IteratorT
const& seqend
)
83 { return false; } // default is to normally expand the macro
86 ///////////////////////////////////////////////////////////////////////////
88 // The function 'expanding_object_like_macro' is called, whenever a
89 // object-like macro is to be expanded .
91 // The parameter 'ctx' is a reference to the context object used for
92 // instantiating the preprocessing iterators by the user.
94 // The parameter 'macro' marks the position, where the macro to expand
97 // The definition 'definition' holds the macro definition for the macro to
100 // The parameter 'macrocall' marks the position, where this macro invoked.
102 // The return value defines, whether the corresponding macro will be
103 // expanded (return false) or will be copied to the output (return true).
105 ///////////////////////////////////////////////////////////////////////////
106 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
108 template <typename TokenT
, typename ContainerT
>
109 void expanding_object_like_macro(TokenT
const& macro
,
110 ContainerT
const& definition
, TokenT
const& macrocall
)
114 template <typename ContextT
, typename TokenT
, typename ContainerT
>
116 expanding_object_like_macro(ContextT
const& ctx
, TokenT
const& macro
,
117 ContainerT
const& definition
, TokenT
const& macrocall
)
118 { return false; } // default is to normally expand the macro
121 ///////////////////////////////////////////////////////////////////////////
123 // The function 'expanded_macro' is called, whenever the expansion of a
124 // macro is finished but before the rescanning process starts.
126 // The parameter 'ctx' is a reference to the context object used for
127 // instantiating the preprocessing iterators by the user.
129 // The parameter 'result' contains the token sequence generated as the
130 // result of the macro expansion.
132 ///////////////////////////////////////////////////////////////////////////
133 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
135 template <typename ContainerT
>
136 void expanded_macro(ContainerT
const& result
)
140 template <typename ContextT
, typename ContainerT
>
141 void expanded_macro(ContextT
const& ctx
, ContainerT
const& result
)
145 ///////////////////////////////////////////////////////////////////////////
147 // The function 'rescanned_macro' is called, whenever the rescanning of a
148 // macro is finished.
150 // The parameter 'ctx' is a reference to the context object used for
151 // instantiating the preprocessing iterators by the user.
153 // The parameter 'result' contains the token sequence generated as the
154 // result of the rescanning.
156 ///////////////////////////////////////////////////////////////////////////
157 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
159 template <typename ContainerT
>
160 void rescanned_macro(ContainerT
const& result
)
164 template <typename ContextT
, typename ContainerT
>
165 void rescanned_macro(ContextT
const& ctx
, ContainerT
const& result
)
169 ///////////////////////////////////////////////////////////////////////////
171 // The function 'found_include_directive' is called, whenever a #include
172 // directive was located.
174 // The parameter 'ctx' is a reference to the context object used for
175 // instantiating the preprocessing iterators by the user.
177 // The parameter 'filename' contains the (expanded) file name found after
178 // the #include directive. This has the format '<file>', '"file"' or
180 // The formats '<file>' or '"file"' are used for #include directives found
181 // in the preprocessed token stream, the format 'file' is used for files
182 // specified through the --force_include command line argument.
184 // The parameter 'include_next' is set to true if the found directive was
185 // a #include_next directive and the BOOST_WAVE_SUPPORT_INCLUDE_NEXT
186 // preprocessing constant was defined to something != 0.
188 // The return value defines, whether the found file will be included
189 // (return false) or will be skipped (return true).
191 ///////////////////////////////////////////////////////////////////////////
192 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
195 found_include_directive(std::string
const& filename
, bool include_next
)
199 template <typename ContextT
>
201 found_include_directive(ContextT
const& ctx
, std::string
const& filename
,
204 return false; // ok to include this file
208 ///////////////////////////////////////////////////////////////////////////
210 // The function 'opened_include_file' is called, whenever a file referred
211 // by an #include directive was successfully located and opened.
213 // The parameter 'ctx' is a reference to the context object used for
214 // instantiating the preprocessing iterators by the user.
216 // The parameter 'filename' contains the file system path of the
217 // opened file (this is relative to the directory of the currently
218 // processed file or a absolute path depending on the paths given as the
219 // include search paths).
221 // The include_depth parameter contains the current include file depth.
223 // The is_system_include parameter denotes, whether the given file was
224 // found as a result of a #include <...> directive.
226 ///////////////////////////////////////////////////////////////////////////
227 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
230 opened_include_file(std::string
const& relname
, std::string
const& absname
,
231 std::size_t include_depth
, bool is_system_include
)
235 template <typename ContextT
>
237 opened_include_file(ContextT
const& ctx
, std::string
const& relname
,
238 std::string
const& absname
, bool is_system_include
)
242 ///////////////////////////////////////////////////////////////////////////
244 // The function 'returning_from_include_file' is called, whenever an
245 // included file is about to be closed after it's processing is complete.
247 // The parameter 'ctx' is a reference to the context object used for
248 // instantiating the preprocessing iterators by the user.
250 ///////////////////////////////////////////////////////////////////////////
251 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
254 returning_from_include_file()
258 template <typename ContextT
>
260 returning_from_include_file(ContextT
const& ctx
)
264 ///////////////////////////////////////////////////////////////////////////
266 // The function 'interpret_pragma' is called, whenever a '#pragma command'
267 // directive is found which isn't known to the core Wave library, where
268 // 'command' is the value defined as the BOOST_WAVE_PRAGMA_KEYWORD constant
269 // which defaults to "wave".
271 // The parameter 'ctx' is a reference to the context object used for
272 // instantiating the preprocessing iterators by the user.
274 // The parameter 'pending' may be used to push tokens back into the input
275 // stream, which are to be used as the replacement text for the whole
276 // #pragma directive.
278 // The parameter 'option' contains the name of the interpreted pragma.
280 // The parameter 'values' holds the values of the parameter provided to
281 // the pragma operator.
283 // The parameter 'act_token' contains the actual #pragma token, which may
284 // be used for error output.
286 // If the return value is 'false', the whole #pragma directive is
287 // interpreted as unknown and a corresponding error message is issued. A
288 // return value of 'true' signs a successful interpretation of the given
291 ///////////////////////////////////////////////////////////////////////////
292 template <typename ContextT
, typename ContainerT
>
294 interpret_pragma(ContextT
const& ctx
, ContainerT
&pending
,
295 typename
ContextT::token_type
const& option
, ContainerT
const& values
,
296 typename
ContextT::token_type
const& act_token
)
301 ///////////////////////////////////////////////////////////////////////////
303 // The function 'defined_macro' is called, whenever a macro was defined
306 // The parameter 'ctx' is a reference to the context object used for
307 // instantiating the preprocessing iterators by the user.
309 // The parameter 'name' is a reference to the token holding the macro name.
311 // The parameter 'is_functionlike' is set to true, whenever the newly
312 // defined macro is defined as a function like macro.
314 // The parameter 'parameters' holds the parameter tokens for the macro
315 // definition. If the macro has no parameters or if it is a object like
316 // macro, then this container is empty.
318 // The parameter 'definition' contains the token sequence given as the
319 // replacement sequence (definition part) of the newly defined macro.
321 // The parameter 'is_predefined' is set to true for all macros predefined
322 // during the initialization phase of the library.
324 ///////////////////////////////////////////////////////////////////////////
325 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
327 template <typename TokenT
, typename ParametersT
, typename DefinitionT
>
329 defined_macro(TokenT
const& macro_name
, bool is_functionlike
,
330 ParametersT
const& parameters
, DefinitionT
const& definition
,
336 typename ContextT
, typename TokenT
, typename ParametersT
,
340 defined_macro(ContextT
const& ctx
, TokenT
const& macro_name
,
341 bool is_functionlike
, ParametersT
const& parameters
,
342 DefinitionT
const& definition
, bool is_predefined
)
346 ///////////////////////////////////////////////////////////////////////////
348 // The function 'undefined_macro' is called, whenever a macro definition
349 // was removed successfully.
351 // The parameter 'ctx' is a reference to the context object used for
352 // instantiating the preprocessing iterators by the user.
354 // The parameter 'name' holds the name of the macro, which definition was
357 ///////////////////////////////////////////////////////////////////////////
358 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
360 template <typename TokenT
>
362 undefined_macro(TokenT
const& macro_name
)
366 template <typename ContextT
, typename TokenT
>
368 undefined_macro(ContextT
const& ctx
, TokenT
const& macro_name
)
372 ///////////////////////////////////////////////////////////////////////////
374 // The function 'found_directive' is called, whenever a preprocessor
375 // directive was encountered, but before the corresponding action is
378 // The parameter 'ctx' is a reference to the context object used for
379 // instantiating the preprocessing iterators by the user.
381 // The parameter 'directive' is a reference to the token holding the
382 // preprocessing directive.
384 // The return value defines, whether the given expression has to be
385 // to be executed in a normal way (return 'false'), or if it has to be
386 // skipped altogether (return 'true'), which means it gets replaced in the
387 // output by a single newline.
389 ///////////////////////////////////////////////////////////////////////////
390 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
392 template <typename TokenT
>
394 found_directive(TokenT
const& directive
)
398 template <typename ContextT
, typename TokenT
>
400 found_directive(ContextT
const& ctx
, TokenT
const& directive
)
401 { return false; } // by default we never skip any directives
404 ///////////////////////////////////////////////////////////////////////////
406 // The function 'evaluated_conditional_expression' is called, whenever a
407 // conditional preprocessing expression was evaluated (the expression
408 // given to a #if, #elif, #ifdef or #ifndef directive)
410 // The parameter 'ctx' is a reference to the context object used for
411 // instantiating the preprocessing iterators by the user.
413 // The parameter 'directive' is a reference to the token holding the
414 // corresponding preprocessing directive.
416 // The parameter 'expression' holds the non-expanded token sequence
417 // comprising the evaluated expression.
419 // The parameter expression_value contains the result of the evaluation of
420 // the expression in the current preprocessing context.
422 // The return value defines, whether the given expression has to be
423 // evaluated again, allowing to decide which of the conditional branches
424 // should be expanded. You need to return 'true' from this hook function
425 // to force the expression to be re-evaluated.
427 ///////////////////////////////////////////////////////////////////////////
428 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
430 template <typename ContainerT
>
432 evaluated_conditional_expression(ContainerT
const& expression
,
433 bool expression_value
)
437 template <typename ContextT
, typename TokenT
, typename ContainerT
>
439 evaluated_conditional_expression(ContextT
const& ctx
,
440 TokenT
const& directive
, ContainerT
const& expression
,
441 bool expression_value
)
442 { return false; } // ok to continue, do not re-evaluate expression
445 ///////////////////////////////////////////////////////////////////////////
447 // The function 'skipped_token' is called, whenever a token is about to be
448 // skipped due to a false preprocessor condition (code fragments to be
449 // skipped inside the not evaluated conditional #if/#else/#endif branches).
451 // The parameter 'ctx' is a reference to the context object used for
452 // instantiating the preprocessing iterators by the user.
454 // The parameter 'token' refers to the token to be skipped.
456 ///////////////////////////////////////////////////////////////////////////
457 #if BOOST_WAVE_USE_DEPRECIATED_PREPROCESSING_HOOKS != 0
459 template <typename TokenT
>
461 skipped_token(TokenT
const& token
)
465 template <typename ContextT
, typename TokenT
>
467 skipped_token(ContextT
const& ctx
, TokenT
const& token
)
471 ///////////////////////////////////////////////////////////////////////////
473 // The function 'generated_token' will be called by the library whenever a
474 // token is about to be returned from the library.
476 // The parameter 'ctx' is a reference to the context object used for
477 // instantiating the preprocessing iterators by the user.
479 // The parameter 't' is the token about to be returned from the library.
480 // This function may alter the token, but in this case it must be
481 // implemented with a corresponding signature:
484 // generated_token(ContextT const& ctx, TokenT& t);
486 // which makes it possible to modify the token in place.
488 // The default behavior is to return the token passed as the parameter
489 // without modification.
491 ///////////////////////////////////////////////////////////////////////////
492 template <typename ContextT
, typename TokenT
>
494 generated_token(ContextT
const& ctx
, TokenT
const& t
)
497 ///////////////////////////////////////////////////////////////////////////
499 // The function 'may_skip_whitespace' will be called by the
500 // library, whenever it must be tested whether a specific token refers to
501 // whitespace and this whitespace has to be skipped.
503 // The parameter 'ctx' is a reference to the context object used for
504 // instantiating the preprocessing iterators by the user.
506 // The 'token' parameter holds a reference to the current token. The policy
507 // is free to change this token if needed.
509 // The 'skipped_newline' parameter holds a reference to a boolean value
510 // which should be set to true by the policy function whenever a newline
511 // is going to be skipped.
513 // If the return value is true, the given token is skipped and the
514 // preprocessing continues to the next token. If the return value is
515 // false, the given token is returned to the calling application.
518 // Caution has to be used, because by returning true the policy function
519 // is able to force skipping even significant tokens, not only whitespace.
521 ///////////////////////////////////////////////////////////////////////////
522 template <typename ContextT
, typename TokenT
>
524 may_skip_whitespace(ContextT
const& ctx
, TokenT
& token
, bool& skipped_newline
)
527 #if BOOST_WAVE_SUPPORT_WARNING_DIRECTIVE != 0
528 ///////////////////////////////////////////////////////////////////////////
530 // The function 'found_warning_directive' will be called by the library
531 // whenever a #warning directive is found.
533 // The parameter 'ctx' is a reference to the context object used for
534 // instantiating the preprocessing iterators by the user.
536 // The parameter 'message' references the argument token sequence of the
537 // encountered #warning directive.
539 // If the return value is false, the library throws a preprocessor
540 // exception of the type 'warning_directive', if the return value is true
541 // the execution continues as if no #warning directive has been found.
543 ///////////////////////////////////////////////////////////////////////////
544 template <typename ContextT
, typename ContainerT
>
546 found_warning_directive(ContextT
const& ctx
, ContainerT
const& message
)
550 ///////////////////////////////////////////////////////////////////////////
552 // The function 'found_error_directive' will be called by the library
553 // whenever a #error directive is found.
555 // The parameter 'ctx' is a reference to the context object used for
556 // instantiating the preprocessing iterators by the user.
558 // The parameter 'message' references the argument token sequence of the
559 // encountered #error directive.
561 // If the return value is false, the library throws a preprocessor
562 // exception of the type 'error_directive', if the return value is true
563 // the execution continues as if no #error directive has been found.
565 ///////////////////////////////////////////////////////////////////////////
566 template <typename ContextT
, typename ContainerT
>
568 found_error_directive(ContextT
const& ctx
, ContainerT
const& message
)
571 ///////////////////////////////////////////////////////////////////////////
573 // The function 'found_line_directive' will be called by the library
574 // whenever a #line directive is found.
576 // The parameter 'ctx' is a reference to the context object used for
577 // instantiating the preprocessing iterators by the user.
579 // The parameter 'arguments' references the argument token sequence of the
580 // encountered #line directive.
582 // The parameter 'line' contains the recognized line number from the #line
585 // The parameter 'filename' references the recognized file name from the
586 // #line directive (if there was one given).
588 ///////////////////////////////////////////////////////////////////////////
589 template <typename ContextT
, typename ContainerT
>
591 found_line_directive(ContextT
const& ctx
, ContainerT
const& arguments
,
592 unsigned int line
, std::string
const& filename
)
595 ///////////////////////////////////////////////////////////////////////////
597 // The function 'throw_exception' will be called by the library whenever a
598 // preprocessing exception occurs.
600 // The parameter 'ctx' is a reference to the context object used for
601 // instantiating the preprocessing iterators by the user.
603 // The parameter 'e' is the exception object containing detailed error
606 // The default behavior is to call the function boost::throw_exception.
608 ///////////////////////////////////////////////////////////////////////////
609 template <typename ContextT
, typename ExceptionT
>
611 throw_exception(ContextT
const& ctx
, ExceptionT
const& e
)
613 boost::throw_exception(e
);
617 ///////////////////////////////////////////////////////////////////////////////
618 } // namespace context_policies
622 // the suffix header occurs after all of the code
623 #ifdef BOOST_HAS_ABI_HEADERS
624 #include BOOST_ABI_SUFFIX
627 #endif // !defined(DEFAULT_PREPROCESSING_HOOKS_HPP_INCLUDED)