]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>The Context Object</title> | |
5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
6 | <link rel="stylesheet" href="theme/style.css" type="text/css"> | |
7 | </head> | |
8 | <body style="color: rgb(0, 0, 0); background-image: url(theme/bkd.gif);"> | |
9 | <table background="theme/bkd2.gif" border="0" cellspacing="2" width="100%"> | |
10 | <tbody> | |
11 | <tr> | |
12 | <td width="21"><h1></h1></td> | |
13 | <td width="885"><font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">The Context Object</font></b></font></td> | |
14 | <td width="96"><a href="http://www.boost.org"><img src="theme/wave.gif" align="right" border="0" height="68" width="93"></a></td> | |
15 | </tr> | |
16 | </tbody> | |
17 | </table> | |
18 | <br> | |
19 | <table border="0"> | |
20 | <tbody> | |
21 | <tr> | |
22 | <td width="10"></td> | |
23 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> | |
24 | <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td> | |
25 | <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td> | |
26 | </tr> | |
27 | </tbody> | |
28 | </table> | |
29 | <blockquote> | |
30 | <p><a href="class_reference_context.html#introduction">Introduction</a><br> | |
31 | <a href="class_reference_context.html#header_synopsis">Header | |
32 | 'wave/context.hpp' synopsis</a><br> | |
33 | <a href="class_reference_context.html#public_typedefs">Public | |
34 | Typedefs</a><br> | |
35 | <a href="class_reference_context.html#template_parameters">Template | |
36 | parameters</a><br> | |
37 | <a href="class_reference_context.html#member_functions">Member | |
38 | functions</a></p> | |
39 | </blockquote> | |
40 | <h2><b><a name="introduction"></a>Introduction</b></h2> | |
41 | <p>The <tt>boost::wave::context<></tt> object is the main user visible object of the <tt>Wave</tt> library. It exists to generate the pair of iterators, which while | |
42 | dereferenced return the preprocessed tokens. Additionally it is used to | |
43 | control other aspects of the preprocessing, such as </p> | |
44 | <blockquote> | |
45 | <p><strong><img id="IMG1" src="theme/bullet.gif" height="13" width="13"></strong> include | |
46 | search paths, which define, where to search for files to be included | |
47 | with <tt>#include <...></tt> and <tt>#include "..."</tt> directives<br> | |
48 | <strong><img src="theme/bullet.gif" height="13" width="13"> </strong>which macros to | |
49 | predefine and which of the predefined macros to undefine<br> | |
50 | <strong><img src="theme/bullet.gif" height="13" width="13"> </strong>several other options as | |
51 | for instance to control, whether to enable several extensions to the | |
52 | C++ Standard (as for instance variadics and placemarkers) or not.</p> | |
53 | </blockquote> | |
54 | <h2><b><a name="header_synopsis"></a>Header <a href="http://svn.boost.org/trac/boost/browser/trunk/boost/wave/cpp_context.hpp">wave/cpp_context.hpp</a> synopsis</b></h2> | |
55 | <pre><span class="keyword">namespace</span> <span class="identifier">boost</span> {<br><span class="keyword">namespace</span> <span class="identifier">wave</span> { <br> <br> <span class="keyword"> struct</span> this_type {};<br><br> <span class="keyword">template</span> <<br> <span class="keyword">typename</span> Iterator, <span class="keyword">typename</span> LexIterator, <br> <span class="keyword">typename</span> InputPolicy, <span class="keyword">typename</span> ContextPolicy,<br> <span class="keyword">typename</span> Derived = this_type<br> > <br> <span class="keyword"> class</span> context <span class="special">:</span> <span class="keyword">public</span> InputPolicy <br> {<br> <span class="keyword">typedef</span> <unspecified> token_sequence_type;<br><br> <span class="keyword">public</span>: <br><br> <span class="keyword"> typedef</span> pp_iterator<context> iterator_type; <br> <span class="keyword">typedef</span> Token token_type;<br> <span class="keyword">typedef</span> <span class="keyword">typename</span> token_type::position_type position_type;<br> <span class="keyword">typedef</span> std::list<token_type> token_sequence_type;<br><br><span class="comment"> // constructor</span><br> <a href="class_reference_context.html#constructor">context</a>(Iterator<span class="keyword"> const</span> &first_, <br> Iterator <span class="keyword">const</span> &last_, <br> <span class="keyword">char const</span> *fname = <span class="string">"<Unknown>"</span>,<br> ContextPolicy <span class="keyword">const</span>& ctx_policy = ContextPolicy())<br><br> <span class="comment">// iterator interface</span><br> iterator_type <a href="class_reference_context.html#iterator_interface_begin">begin</a>() <span class="keyword">const</span>;<br> iterator_type <a href="class_reference_context.html#iterator_interface_begin">begin</a>(Iterator<span class="keyword"> const</span> &first, <br> Iterator <span class="keyword">const</span> &last) <span class="keyword">const</span>;<br> iterator_type <a href="class_reference_context.html#iterator_interface_end">end</a>() <span class="keyword">const</span>;<br><br> <span class="comment">// maintain include paths</span><br><span class="keyword"> bool</span> <a href="class_reference_context.html#add_include_path">add_include_path</a>(<span class="keyword">char const</span> *path_);<br> <span class="keyword">bool</span> <a href="class_reference_context.html#add_sysinclude_path">add_sysinclude_path</a>(<span class="keyword">char const</span> *path_);<br> <span class="keyword">void</span> <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter</a>();<br> <br> size_t <a href="class_reference_context.html#get_iteration_depth">get_iteration_depth</a>() <span class="keyword">const</span>;<br><br> <span class="comment"> // maintain defined macros</span><br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br><span class="keyword"> bool</span> <a href="class_reference_context.html#add_macro_definition">add_macro_definition</a>(<span class="keyword">String</span> macrostring, <br> <span class="keyword"> bool</span> is_predefined = <span class="keyword">false</span>);<br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br><span class="keyword"></span> <span class="keyword">bool</span> add_macro_definition(StringT <span class="keyword">const</span> &name, <br> position_type <span class="keyword">const</span>& pos, <span class="keyword">bool</span> has_params, <br> std::vector<token_type> &parameters, <br> token_sequence_type &definition, <br> <span class="keyword">bool</span> is_predefined = <span class="keyword">false</span>)<br><br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> <a href="class_reference_context.html#is_defined_macro">is_defined_macro</a>(<span class="keyword">String const</span> &name) <span class="keyword">const</span>;<br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> <a href="class_reference_context.html#remove_macro_definition">remove_macro_definition</a>(String<span class="keyword"> const</span> &name, <br> <span class="keyword"> bool</span> even_predefined = <span class="keyword">false</span>);<br> <span class="keyword">void</span> <a href="class_reference_context.html#reset_macro_definitions">reset_macro_definitions</a>();<br> <span class="keyword">template</span> <<span class="keyword">typename</span> String><br> <span class="keyword"> bool</span> <a href="class_reference_context.html#get_macro_definition">get_macro_definition</a>(<br> <span class="keyword"> </span>String<span class="keyword"> const</span> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword"><br> bool</span> &is_predefined, position_type &pos, <br> std::vector<token_type> &parameters, <br> token_sequence_type &definition) <span class="keyword">const</span>; <br><br> <span class="keyword">typedef</span> <unspecified> macromap_type;<br> <span class="keyword">typedef</span> typename macromap_type::name_iterator name_iterator;<br> <span class="keyword">typedef</span> typename macromap_type::const_name_iterator const_name_iterator;<br><br> name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>();<br> name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>();<br> const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>() <span class="keyword">const</span>;<br> const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>() <span class="keyword">const</span>;<br><br> <span class="comment">// other options</span><br><span class="keyword"> void</span> <a href="class_reference_context.html#language_support">set_language</a>(language_support enable);<br> language_support <a href="class_reference_context.html#language_support">get_language</a>() <span class="keyword">const</span>;<br><br><span class="keyword"> void</span> <a href="class_reference_context.html#set_max_include_nesting_depth">set_max_include_nesting_depth</a>(std::size_t new_depth);<br> size_t <a href="class_reference_context.html#set_max_include_nesting_depth">get_max_include_nesting_depth</a>() <span class="keyword">const</span>;<br><br><span class="comment"> // get the Wave version information </span><br><span class="keyword"> static std::string</span> <a href="class_reference_context.html#get_version">get_version</a>();<br> <span class="keyword">static std::string</span> <a href="class_reference_context.html#get_version">get_version_string</a>();<br> };<br><br>} <span class="comment">// namespace wave</span><br>} <span class="comment">// namespace boost</span></pre> | |
56 | <h2><b><a name="template_parameters"></a>Template | |
57 | parameters</b></h2> | |
58 | <p>The <tt>boost::wave::context</tt> object has | |
59 | three template parameters to specify the concrete behaviour of its | |
60 | operation. The following table describes these with more detail.</p> | |
61 | <table align="center" border="0" width="90%"> | |
62 | <tbody> | |
63 | <tr> | |
64 | <td colspan="2" class="table_title"><b>Template | |
65 | parameters required for the <tt>boost::wave::context</tt> class </b></td> | |
66 | </tr> | |
67 | <tr> | |
68 | <td class="table_cells" width="32%"><code>Iterator</code></td> | |
69 | <td class="table_cells" width="68%"><p>The type of the underlying iterator, through which the | |
70 | input stream is accessed. <br> | |
71 | This should be at least an <tt>forward_iterator</tt> type | |
72 | iterator.</p></td> | |
73 | </tr> | |
74 | <tr> | |
75 | <td class="table_cells"><code>LexIterator</code></td> | |
76 | <td class="table_cells"><p>The type of the lexer type to be used by the <tt>Wave</tt> library to identify tokens in the input stream.</p></td> | |
77 | </tr> | |
78 | <tr> | |
79 | <td class="table_cells"><code>InputPolicy</code></td> | |
80 | <td class="table_cells"><p>The type of the input policy class, which allows to | |
81 | customize the behaviour of the Wave library and the type of the | |
82 | iterators to use, when it comes to including and opening an included | |
83 | file.</p></td> | |
84 | </tr> | |
85 | <tr> | |
86 | <td class="table_cells"><code>ContextPolicy</code></td> | |
87 | <td class="table_cells"><p>The type of the context policy class, which allows to | |
88 | customize different aspects of the behaviour of the preprocessing. The | |
89 | requirements of this policy and the available customization points | |
90 | provided by this policy are described <a href="class_reference_ctxpolicy.html">here</a>. | |
91 | </p></td> | |
92 | </tr> | |
93 | <tr class="table_cells"> | |
94 | <td class="table_cells"><code>Derived</code></td> | |
95 | <td><p>The type of the type being derived from the context type (if | |
96 | any). This template parameter is optional and defaults to 'this_type', | |
97 | which means that the context type will be used assuming no derived type exists. <br> | |
98 | </p></td> | |
99 | </tr> | |
100 | </tbody> | |
101 | </table> | |
102 | <p>For further information about the lexer type to use, please | |
103 | refer to the <a href="class_reference_lexer.html">The | |
104 | Lexer Interface </a>.</p> | |
105 | <p>If the template parameter <tt>InputPolicy</tt> is | |
106 | omitted, the template <tt>boost::wave::iteration_context_policies::load_file_to_string</tt> is used. For further information about the input policy, please refer | |
107 | to the topic <a href="class_reference_inptpolcy.html">The | |
108 | Input Policy</a>.</p> | |
109 | <p>If the template parameter ContextPolicy is omitted, the <tt>boost::wave::context_policies::eat_whitespace</tt> policy type is used, implementing certain basic preprocessing hooks | |
110 | needed for normal (default) execution. For further information about | |
111 | the context policy, please refer to the topic <a href="class_reference_ctxpolicy.html">The Context Policy</a>. </p> | |
112 | <h2><a name="public_typedefs"></a>Public | |
113 | Typedefs</h2> | |
114 | <p>The <tt>boost::wave::context</tt> template | |
115 | defines the following public typedefs, which may be useful while using | |
116 | this class:</p> | |
117 | <table align="center" border="0" width="90%"> | |
118 | <tbody> | |
119 | <tr> | |
120 | <td colspan="2" class="table_title"><b>Public | |
121 | typedef's defined by the <tt>boost::wave::context</tt> class </b></td> | |
122 | </tr> | |
123 | <tr> | |
124 | <td class="table_cells"><code>iterator_type</code></td> | |
125 | <td class="table_cells"><p>The <tt>Iterator</tt> template parameter | |
126 | provided, while the <tt>context</tt> class was | |
127 | instantiated. </p></td> | |
128 | </tr> | |
129 | <tr> | |
130 | <td class="table_cells"><code>lex_type</code></td> | |
131 | <td class="table_cells"><p>The <tt>LexIterator</tt> template parameter | |
132 | provided, while the <tt>context</tt> class was | |
133 | instantiated. </p></td> | |
134 | </tr> | |
135 | <tr> | |
136 | <td class="table_cells" width="32%"><code>token_type</code></td> | |
137 | <td class="table_cells" width="68%"><p>The token type, which is returned by the <tt>context</tt> generated iterators. This type is taken from the <tt>LexIterator</tt> template parameter provided, whicle the <tt>context</tt> class was instantiated.</p></td> | |
138 | </tr> | |
139 | <tr> | |
140 | <td class="table_cells"><code>input_policy_type</code></td> | |
141 | <td class="table_cells"><p>The <tt>InputPolicy</tt> template parameter | |
142 | provided, while the <tt>context</tt> class was | |
143 | instantiated. </p></td> | |
144 | </tr> | |
145 | <tr> | |
146 | <td class="table_cells"><code>context_policy_type</code></td> | |
147 | <td class="table_cells"><p>The <tt>ContextPolicy</tt> template | |
148 | parameter provided, while the <tt>context</tt> class was | |
149 | instantiated. </p></td> | |
150 | </tr> | |
151 | <tr> | |
152 | <td class="table_cells"><code>position_type</code></td> | |
153 | <td class="table_cells"><p>The type of the position information contained in every | |
154 | returned token, which describes the point, at which the given token was | |
155 | recognised. </p></td> | |
156 | </tr> | |
157 | </tbody> | |
158 | </table> | |
159 | <h2><b><a name="member_functions"></a>Member | |
160 | functions</b></h2> | |
161 | <p><b><a name="constructor" id="constructor"></a>Constructor</b></p> | |
162 | <pre> context(Iterator <span class="keyword">const</span> &first, <br> Iterator <span class="keyword">const</span> &last, <span class="keyword">char</span> <span class="keyword">const</span> *filename, <br> ContextPolicy <span class="keyword">const</span>& ctx_policy);</pre> | |
163 | <p>Constructs a context object on top of the input stream given | |
164 | by the pair of auxilliary iterators <tt>[first, last)</tt>. | |
165 | The iterators should be at least <tt>forward_iterator</tt> type iterators. The filename parameter is to be supplied for | |
166 | informational purposes only. This string is used for indicating the | |
167 | token positions inside the input stream, it is not validated against | |
168 | the file system. If the filename parameter is not given it defaults to <span class="copyright">"<Unknown>"</span>. If | |
169 | the ctx_policy parameter isn't supplied it defaults to a default | |
170 | constructed <tt>ContextPolicy</tt> object. </p> | |
171 | <p>Additionally the macro symbol table is filled with the | |
172 | predefined macros and the current reference directory is set to the | |
173 | path of the given filename. If this filename does not reference valid | |
174 | file system item, the current reference directory is set to the current | |
175 | system directory. (The current reference directory is the file system | |
176 | path, which is used as the target directory during the processing of <tt>#include "..."</tt> directives).</p> | |
177 | <h3>Iterator interface</h3> | |
178 | <p>The pair of iterators returned by the <tt>context::begin</tt> and <tt>context::end</tt> functions is the main interface | |
179 | for accessing the preprocessed tokens from the preprocessor engine. | |
180 | While iterating over the given iterator range <tt>[begin, end)</tt> there are returned the preprocessed C++ tokens, which are generated on | |
181 | the fly from the underlying input stream. The returned iterators are | |
182 | conceptually of <tt>forward_iterator</tt> type.</p> | |
183 | <p><b><a name="iterator_interface_begin"></a></b><b>begin</b></p> | |
184 | <pre> iterator_type begin();<br> iterator_type begin(Iterator <span class="keyword">const</span> &first,<br> Iterator <span class="keyword">const</span> &last, <span class="keyword"></span>);</pre> | |
185 | <blockquote> | |
186 | <p>Initializes and returns the starting iterator for the | |
187 | preprocessed token stream. The iterator pair given by the parameters <tt>[first, last)</tt> specifies the input sequence to preprocess. The first version of this | |
188 | function uses the iinput stream as specified by the constructor. </p> | |
189 | </blockquote> | |
190 | <p><b><a name="iterator_interface_end" id="iterator_interface_end"></a></b><b>end</b></p> | |
191 | <pre> iterator_type end() <span class="keyword">const</span>;</pre> | |
192 | <blockquote> | |
193 | <p>Initializes and returns the end of stream iterator to | |
194 | compare with for detecting the end of the preprocessed token stream.</p> | |
195 | </blockquote> | |
196 | <h3>Maintain include paths</h3> | |
197 | <p>The <tt>Wave</tt> library maintains two separate | |
198 | search paths for include files. A search path for user include files | |
199 | and a search path for system include files. Any directories specified | |
200 | with the <a href="#add_include_path">add_include_path()</a> function before the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> is called are searched only for the case of <tt>#include "..."</tt> directives, they are not searched for <tt>#include <file></tt> directives. I.e. these directories are added to the user include search | |
201 | path. </p> | |
202 | <p>If additional directories are specified with the <a href="#add_include_path">add_include_path()</a> function after a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a>, | |
203 | these directories are searched for all <tt>#include</tt> directives. I.e. these directories are added to the system include | |
204 | search path.</p> | |
205 | <p>In addition, a call to the function <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> inhibits the use of the current reference directory as the first search | |
206 | directory for <tt>#include "..."</tt> directives. | |
207 | Therefore, the current reference directory is searched only, if it is | |
208 | requested explicitly with a call to the function <a href="#add_include_path">add_include_path(".")</a>. </p> | |
209 | <p>Callig both functions, the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> and <a href="#add_include_path">add_include_path(".")</a> allows you to control precisely, which directories are searched before | |
210 | the current one and which are searched after.</p> | |
211 | <p>These functions are modelled after the command line behaviour | |
212 | implemented by the popular gcc compiler.<br> | |
213 | </p> | |
214 | <p><a name="add_include_path"></a><b>add_include_path</b></p> | |
215 | <pre> <span class="keyword"> bool</span> add_include_path(<span class="keyword">char const</span> *path);<br> | |
216 | </pre> | |
217 | <blockquote> | |
218 | <p>Adds the given file system path to the user include search | |
219 | paths. After a call to the <a href="class_reference_context.html#set_sysinclude_delimiter">set_sysinclude_delimiter()</a> this function adds the given file system path to the system include | |
220 | search paths. Note though, that the given path is validated against the | |
221 | file system. </p> | |
222 | <p>If the given path string does not form a name of a valid | |
223 | file system directory item, the function returns <tt>false</tt>. | |
224 | If the given path was successfully added to the include search paths in | |
225 | question, the function returns <tt>true</tt>.</p> | |
226 | </blockquote> | |
227 | <p><a name="add_sysinclude_path"></a><b>add_sysinclude_path</b></p> | |
228 | <pre> <span class="keyword">bool</span> add_sysinclude_path(<span class="keyword">char const</span> *path);</pre> | |
229 | <blockquote> | |
230 | <p>Adds the given file system path to the system include search | |
231 | paths. This function operates on the system include search path | |
232 | regardless of the mode of operation of the <a href="#add_include_path">add_include_path()</a>. Note | |
233 | though, that the given path is validated against the file system.</p> | |
234 | <p>If the given path string does not form a name of a valid | |
235 | file system directory item, the function returns <tt>false</tt>. | |
236 | If the given path was successfully added to the system include search | |
237 | paths, the function returns <tt>true</tt>.</p> | |
238 | </blockquote> | |
239 | <p><a name="set_sysinclude_delimiter"></a><b>set_sysinclude_delimiter</b></p> | |
240 | <pre> <span class="keyword"> void</span> set_sysinclude_delimiter();</pre> | |
241 | <blockquote> | |
242 | <p>Switches the mode, how the <a href="#add_include_path">add_include_path()</a> function operates. By default the given file system path is added to | |
243 | the user include search paths. After calling this function a subsequent | |
244 | call to the <a href="#add_include_path">add_include_path()</a> adds the given file system path to the system include search paths. | |
245 | Additionally it inhibits the the use of the current reference directory | |
246 | as the first search directory for <tt>#include "..."</tt> directives.</p> | |
247 | </blockquote> | |
248 | <p><a name="get_iteration_depth"></a><b>get_iteration_depth</b></p> | |
249 | <pre> size_t get_iteration_depth() <span class="keyword">const</span>;</pre> | |
250 | <blockquote> | |
251 | <p>Returns the actual include iteration depth, i.e. the current | |
252 | number of include levels to be poped from the include iteration | |
253 | context, before the main (topmost) iteration context is reached.</p> | |
254 | </blockquote> | |
255 | <h3>Maintain defined macros</h3> | |
256 | <p><a name="add_macro_definition"></a><b>add_macro_definition</b></p> | |
257 | <pre><span class="keyword"> bool</span> add_macro_definition(<br> <span class="keyword"> std::string</span> macrostring, <span class="keyword">bool</span> is_predefined); <br> | |
258 | </pre> | |
259 | <blockquote> | |
260 | <p>Adds a new macro definition to the macro symbol table. The | |
261 | parameter <tt>macrostring</tt> should contain the macro to | |
262 | define in the command line format, i.e. something like <tt>MACRO(x)=definition</tt>. | |
263 | The following table describes this format in more detail. The parameter <tt>is_predefined</tt> should be true while defining | |
264 | predefined macros, i.e. macros, which are not undefinable with an <tt>#undef</tt> directive from inside the preprocessed input stream. If this parameter | |
265 | is not given, it defaults to <tt>false</tt>.</p> | |
266 | <table align="center" border="0" width="90%"> | |
267 | <tbody> | |
268 | <tr> | |
269 | <td colspan="2" class="table_title"><b>Summary | |
270 | of possible formats for defining macros </b></td> | |
271 | </tr> | |
272 | <tr> | |
273 | <td class="table_cells" width="32%"><code>MACRO</code></td> | |
274 | <td class="table_cells" width="68%"><code>define <tt>MACRO</tt> as 1</code></td> | |
275 | </tr> | |
276 | <tr> | |
277 | <td class="table_cells"><code>MACRO=</code></td> | |
278 | <td class="table_cells"><code>define <tt>MACRO</tt> as nothing (empty)</code></td> | |
279 | </tr> | |
280 | <tr> | |
281 | <td class="table_cells"><code>MACRO=definition</code></td> | |
282 | <td class="table_cells"><code>define <tt>MACRO</tt> as <tt>definition</tt></code></td> | |
283 | </tr> | |
284 | <tr> | |
285 | <td class="table_cells" width="32%"><code>MACRO(x)</code></td> | |
286 | <td class="table_cells" width="68%"><code>define <tt>MACRO(x)</tt> as 1</code></td> | |
287 | </tr> | |
288 | <tr> | |
289 | <td class="table_cells"><code>MACRO(x)=</code></td> | |
290 | <td class="table_cells"><code>define <tt>MACRO(x)</tt> as nothing (empty)</code></td> | |
291 | </tr> | |
292 | <tr> | |
293 | <td class="table_cells"><code>MACRO(x)=definition</code></td> | |
294 | <td class="table_cells"><code>define <tt>MACRO(x)</tt> as <tt>definition</tt></code></td> | |
295 | </tr> | |
296 | </tbody> | |
297 | </table> | |
298 | <p>The function returns <tt>false</tt>, if the | |
299 | macro to define already was defined and the new definition is | |
300 | equivalent to the existing one, it returns true, if the new macro was | |
301 | successfully added to the macro symbol table.</p> | |
302 | <p>If the given macro definition resembles a redefinition and | |
303 | the new macro is not identical to the already defined macro (in the | |
304 | sense defined by the C++ Standard), the function throws a corresponding <tt>preprocess_exception</tt>.</p> | |
305 | </blockquote> | |
306 | <p><a name="is_defined_macro"></a><b>is_defined_macro</b></p> | |
307 | <pre> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> is_defined_macro(String <span class="keyword">const</span> &name) <span class="keyword">const</span>; </pre> | |
308 | <blockquote> | |
309 | <p>Returns, if a macro with the given <tt>name</tt> is defined, i.e. if it is contained in the macro symbol table.</p> | |
310 | </blockquote> | |
311 | <p><strong><a name="get_macro_definition"></a>get_macro_definition</strong></p> | |
312 | <pre> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br> <span class="keyword">bool</span> get_macro_definition(<br> <span class="keyword"> </span>String<span class="keyword"> const</span> &name, <span class="keyword">bool</span> &is_function_style, <span class="keyword"><br> bool</span> &is_predefined, position_type &pos, <br> std::vector<token_type> &parameters, <br> token_sequence_type &definition) <span class="keyword">const</span>; </pre> | |
313 | <blockquote> | |
314 | <p>Allows to retrieve all information known with regard to a | |
315 | macro definition. The parameter <tt>name</tt> specifies | |
316 | the name of the macro the information should be returned for. The | |
317 | parameters <tt>is_function_style</tt> and <tt>is_predefined</tt> return, whether the macro has been defined as a function style macro or | |
318 | as a predefined macro resp. The parameter <tt>pos</tt> will contain the position the macro was defined at. The parameter <tt>parameters</tt> will contain the names of the parameters the macro was defined with and | |
319 | the parameter <tt>definition</tt> will contain the token | |
320 | sequence for the definition (macro body).</p> | |
321 | <p>The function returns <tt>true</tt> is the macro | |
322 | was defined and the requested information has been successfully | |
323 | retrieved, <tt>false</tt> otherwise.</p> | |
324 | </blockquote> | |
325 | <p><a name="remove_macro_definition"></a><b>remove_macro_definition</b></p> | |
326 | <pre><span class="keyword"> </span> <span class="keyword"> template</span> <<span class="keyword">typename</span> String><br><span class="keyword"> bool</span> remove_macro_definition(<br> String<span class="keyword"> const</span> &name, <span class="keyword">bool</span> even_predefined); </pre> | |
327 | <blockquote> | |
328 | <p>Removes the definition of the macro with the given <tt>name</tt> from the macro symbol table. This operation is equivalent to an <tt>#undef</tt> directive with this <tt>name</tt> executed from within the | |
329 | input stream. If the parameter <tt>even_predefined</tt> is <tt>true</tt>, then the macro is removed from the macro | |
330 | symbol table even, if it is defined as a predefined macro. </p> | |
331 | <p>Note though, that the following macros are <b>not</b> undefinable in any case: <tt>__FILE__</tt>, <tt>__LINE__</tt>, <tt>__DATE__</tt>, <tt>__TIME__</tt>, <tt>__cplusplus</tt>, <tt>__STDC__</tt>. If the parameter <tt>even_predefined</tt> is not given, it defaults to <tt>false</tt>.</p> | |
332 | <p>The function returns <tt>false</tt>, if the | |
333 | macro to undefine was not defined and returns <tt>true</tt> otherwise.</p> | |
334 | <p>If the macro to remove may not be undefined (it is a | |
335 | predefined macro and the parameter <tt>even_predefined</tt> is set to <tt>false</tt> or it is one of the mentioned not | |
336 | undefinable macros above) the function throws a <tt>preprocess_exception</tt>.</p> | |
337 | </blockquote> | |
338 | <p><a name="reset_macro_definitions"></a><b>reset_macro_definitions</b></p> | |
339 | <pre><span class="keyword"> void</span> reset_macro_definitions(); </pre> | |
340 | <blockquote> | |
341 | <p>Resets the macro symbol table to it's initial state, i.e. | |
342 | undefines all user defined macros and inserts the internal predefined | |
343 | macros as described <a href="predefined_macros.html">here</a>.</p> | |
344 | </blockquote> | |
345 | <p><a name="macro_names_iterators"></a><b>macro_names_begin, | |
346 | macro_names_end </b></p> | |
347 | <pre> name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>();<br> name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>();<br> const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_begin</a>() <span class="keyword">const</span>;<br> const_name_iterator <a href="class_reference_context.html#macro_names_iterators">macro_names_end</a>() <span class="keyword">const</span>;<br> | |
348 | </pre> | |
349 | <blockquote> | |
350 | <p>The <tt>macro_names_begin</tt> and <tt>macro_names_end</tt> functions return iterators allowing to iterate on the names of all | |
351 | defined macros.</p> | |
352 | </blockquote> | |
353 | <h3><a name="get_version"></a>Get Version | |
354 | information</h3> | |
355 | <p><b>get_version</b></p> | |
356 | <pre><span class="keyword"> </span><span class="keyword"> static std::string</span> get_version(); </pre> | |
357 | <blockquote> | |
358 | <p>Returns a string containing the current Wave version | |
359 | formatted as <span class="string">0xvvrsbbbb</span> (this is a string representation of the equivalent hexadecimal number), | |
360 | where <span class="literal">'vv'</span> is the | |
361 | version number, <span class="literal">'r'</span> the release number, <span class="literal">'s'</span> the subrelease number and <span class="literal">'bbbb'</span> the build number. A possible return value looks like <span class="literal">0x00910454</span>. The returned value | |
362 | is the same as is inserted in the preprocessed token stream, when the | |
363 | predefined macro <tt>__WAVE_VERSION__</tt> is expanded.</p> | |
364 | </blockquote> | |
365 | <p><b>get_version_str</b></p> | |
366 | <pre><span class="keyword"> </span><span class="keyword"> static std::string</span> get_version_str(); </pre> | |
367 | <blockquote> | |
368 | <p>Returns a string containing the current Wave version | |
369 | formatted as <span class="string">"v.rr.ss.bbbb"</span>, | |
370 | where <span class="literal">'v'</span> is the | |
371 | version number, <span class="literal">'rr'</span> the release number, <span class="literal">'ss'</span> the subrelease number and <span class="literal">'bbbb'</span> the build number. A possible return value looks like <span class="literal">"0.9.1.454"</span>. The returned value | |
372 | is the same as it will be inserted in the preprocessed token stream, | |
373 | when the predefined macro <tt>__WAVE_VERSION_STR__</tt> is | |
374 | expanded.</p> | |
375 | </blockquote> | |
376 | <h3>Control extended options</h3> | |
377 | <p><a name="language_support"></a>set_language<br> | |
378 | get_language</p> | |
379 | <pre><span class="keyword"> void</span> set_language(<span class="keyword">language_support</span> language, <br> <span class="keyword">bool</span> reset_macros = <span class="keyword">true</span>);<br> <span class="keyword">language_support</span> get_language() <span class="keyword">const</span>;</pre> | |
380 | <blockquote> | |
381 | <p>This functions allows to specify the language mode, in which | |
382 | the <tt>Wave</tt> library should work. The possible | |
383 | language modes are defined by the enumerated type <tt>language_support</tt>:</p> | |
384 | <pre> <span class="keyword">enum</span> language_support {<br> <span class="comment">// support flags for C++98</span><br> support_normal = 0x01,<br> support_cpp = support_normal,<br><span class="comment"><br> // support flags for C99</span><br> support_option_long_long = 0x02,<br> support_option_variadics = 0x04,<br> support_c99 = support_option_variadics | support_option_long_long | 0x08,<br><span class="comment"><br> // the mask for the main language settings</span><br> support_option_mask = 0xFFB0,<br><br><span class="comment"> // additional fine tuning of the general behavior</span> | |
385 | support_option_emit_contline = 0x0040,<br> support_option_insert_whitespace = 0x0080,<br> support_option_preserve_comments = 0x0100,<br> support_option_no_character_validation = 0x0200,<br> support_option_convert_trigraphs = 0x0400,<br> support_option_single_line = 0x0800,<br> support_option_prefer_pp_numbers = 0x1000,<br> support_option_emit_line_directives = 0x2000,<br> support_option_include_guard_detection = 0x4000,<br> support_option_emit_pragma_directives = 0x8000<br> };</pre> | |
386 | <p>When used with <tt>support_option_variadics</tt> the support for variadics, placemarkers and the <tt>operator _Pragma()</tt> is enabled in normal C++ mode. When used with the <tt>support_option_long_long</tt> the support for long long suffixes is enabled in C++ mode. </p> | |
387 | <p>The <tt>support_c99</tt> switches on the C99 | |
388 | language support, which enables variadics, placemarkers, the <tt>operator _Pragma</tt> and long long suffixes by default. Additionally it disables the C++ | |
389 | specific tokens such as <tt>'->*'</tt>, <tt>'.*'</tt>, <tt>'::'</tt> etc. </p> | |
390 | <p>The <tt>support_option_...</tt> values are to | |
391 | be used in conjunction with the main language settings (<tt>support_normal</tt> and <tt>support_c99</tt>) . </p> | |
392 | <ul> | |
393 | <li>If the <tt>support_option_insert_whitespace</tt> flag is set, the <tt>Wave</tt> library inserts | |
394 | additional whitespace between tokens where the concatenated string | |
395 | representation of the two tokens would form another valid C++ token. | |
396 | This is very importatnt to avoid mis-interpretations of the generated | |
397 | output if it is going to be processed by a C++ compiler afterwards. | |
398 | </li> | |
399 | <li>If the <tt>support_option_preserve_comments</tt> flag is set, the <tt>Wave</tt> library preserves almost | |
400 | all comments in the source code. The only comments not preserved are | |
401 | those contained inside macro definitions. If this flag is not set all | |
402 | comments are replaced by a single space. </li> | |
403 | <li>If the <tt>support_option_no_character_validation</tt> flag is set , the <tt>Wave</tt> library does not validate | |
404 | universal character literals (given in the form of <tt>'u1234'</tt> or <tt>'U12345678'</tt>) to be in the allowed value range. | |
405 | This flag is merely used for internal purposes by the testing framework | |
406 | and will be rarely used by a user of the library.</li> | |
407 | <li>If the <tt>support_option_convert_trigraphs</tt> flag is set, the <tt>Wave</tt> library replaces all | |
408 | occurences of trigraph characters with their non-trigraph character | |
409 | sequence (i.e. <tt>'??='</tt> is replaced by <tt>'#'</tt> etc.) . By default no replacement is performed. </li> | |
410 | <li>If the <tt>support_option_single_line</tt> flag is set, the <tt>Wave</tt> library will now reprot an | |
411 | error if the last line of the processed input is not terminated by a | |
412 | new line. This flag is merely used for internal purposes by the testing | |
413 | framework and will be rarely used by a user of the library.</li> | |
414 | <li>If the <tt>support_option_prefer_pp_numbers</tt> flag is set, the <tt>Wave</tt> library is instructed to | |
415 | correctly identify pp-number's in the input stream. These get | |
416 | recognized into 'normal' number tokens before they get returned to the | |
417 | calling application. The flag is set by default and is used merely for | |
418 | internal purposes and will be rarely reset by a user of the library. </li> | |
419 | <li>If the <span class="keyword">support_option_emit_line_directives</span> flag is set, the <tt>Wave</tt> library will emit <span class="preprocessor">#line</span> directives in the | |
420 | generated token stream, if appropriate. This flag is set by default, to | |
421 | prevent the library from generating <span class="preprocessor">#line</span> directives it must be reset explicitely. </li> | |
422 | <li>If the <span class="keyword">support_option_include_guard_detection</span> flag is set, the <tt>Wave</tt> library will try to | |
423 | automatically identify include guards during the processing of a | |
424 | included file. Files which contained include guards are handled as if | |
425 | they contained a #pragma once, i.e. these files wonn#t be opened twice, | |
426 | even if specified in a second <span class="preprocessor">#include</span> statement. </li> | |
427 | </ul> | |
428 | <blockquote> | |
429 | <p>During this process the library will recognize two forms | |
430 | of include guards:</p> | |
431 | <pre> <span class="preprocessor">#ifndef</span> INCLUDE_GUARD_MACRO<br> <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO<br> ...<br> <span class="preprocessor">#endif</span><br>or<br><span class="preprocessor"> #if</span> !defined(INCLUDE_GUARD_MACRO)<br> <span class="preprocessor">#define</span> INCLUDE_GUARD_MACRO<br> ...<br> <span class="preprocessor">#endif</span></pre> | |
432 | <p> Note, that the parenthesis in the second form are | |
433 | optional (i.e. <tt>!defined INCLUDE_GUARD_MACRO</tt> will | |
434 | work as well). The code allows for any whitespace, newline and single | |
435 | '#' tokens before the <span class="preprocessor">#if</span>/<span class="preprocessor">#ifndef</span> and after the | |
436 | final <span class="preprocessor">#endif</span> for | |
437 | the include guard to be recognized.</p> | |
438 | <p>This flag is on by default, so if you do not want the | |
439 | library to automatically reconize include guards you will need to reset | |
440 | this explicitely. </p> | |
441 | </blockquote> | |
442 | <ul> | |
443 | <li>If the <tt>support_option_emit_pragma_directives</tt> flag is set, the <tt>Wave</tt> library will emit all | |
444 | unknown <span class="preprocessor">#pragma</span> directives to the output. This suport option will be recognized only if | |
445 | the <tt>BOOST_WAVE_EMIT_PRAGMA_DIRECTIVES</tt> is defined | |
446 | during compilation to a value not equal to zero (see <a href="compiletime_config.html">here</a> for more | |
447 | information). </li> | |
448 | <li>If the <tt>support_option_emit_contlines</tt> flag is set, the <tt>Wave</tt> library will emit all backslash newline sequences encountered in the input. It will generate a <tt>T_CONTLINE</tt> token for each of those character sequences. Please note that this option is supported by the custom SLex lexer module only. See the cpp_tokens example for a working example.</li> | |
449 | </ul> | |
450 | <p><strong> </strong>If the parameter <tt>reset_macros</tt> is true the <tt>set_language</tt> function internally | |
451 | resets the list of defined macros, so please be careful not to call it | |
452 | after you have defined your own macros already. </p> | |
453 | </blockquote> | |
454 | <p><a name="set_max_include_nesting_depth" id="set_max_include_nesting_depth"></a>set_max_include_nesting_depth<br> | |
455 | get_max_include_nesting_depth</p> | |
456 | <pre><span class="keyword"> void</span> set_max_include_nesting_depth(size_t new_depth); <br> size_t get_max_include_nesting_depth() <span class="keyword">const</span>;</pre> | |
457 | <blockquote> | |
458 | <p>This functions allow to set or to get the maximal possible | |
459 | include file nesting depth supported by the <tt>Wave</tt> library. The initial value for this is determined by the preprocessing | |
460 | constant <tt>WAVE_MAX_INCLUDE_LEVEL_DEPTH</tt> (see <a href="compiletime_config.html">here</a>).</p> | |
461 | </blockquote> | |
462 | <table border="0"> | |
463 | <tbody> | |
464 | <tr> | |
465 | <td width="10"></td> | |
466 | <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> | |
467 | <td width="30"><a href="quickstart.html"><img src="theme/l_arr.gif" border="0" height="19" width="20"></a></td> | |
468 | <td width="30"><a href="class_reference_inptpolcy.html"><img src="theme/r_arr.gif" border="0"></a></td> | |
469 | </tr> | |
470 | </tbody> | |
471 | </table> | |
472 | <hr size="1"> | |
473 | <p class="copyright">Copyright © 2003-2011 Hartmut Kaiser<br> | |
474 | <br> | |
475 | <font size="2">Distributed under the Boost Software | |
476 | License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at | |
477 | http://www.boost.org/LICENSE_1_0.txt) </font> </p> | |
478 | <span class="updated"></span> | |
479 | <p class="copyright"><span class="updated">Last | |
480 | updated: | |
481 | <!-- #BeginDate format:fcAm1m -->Saturday, August 6, 2011 20:22<!-- #EndDate --> | |
482 | </span> </p> | |
483 | <p> </p> | |
484 | </body> | |
485 | </html> |