]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Hartmut Kaiser | |
3 | Copyright (C) 2001-2011 Joel de Guzman | |
4 | ||
5 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
6 | file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
7 | ===============================================================================/] | |
8 | ||
9 | [section:auxiliary Auxiliary Generators] | |
10 | ||
11 | This module includes different auxiliary generators not fitting into any of the | |
12 | other categories. It includes the `attr_cast`, `eol`, `eps`, and `lazy` | |
13 | generators. | |
14 | ||
15 | [heading Module Header] | |
16 | ||
17 | // forwards to <boost/spirit/home/karma/auxiliary.hpp> | |
18 | #include <boost/spirit/include/karma_auxiliary.hpp> | |
19 | ||
20 | Also, see __include_structure__. | |
21 | ||
22 | [/////////////////////////////////////////////////////////////////////////////] | |
23 | [section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)] | |
24 | ||
25 | [heading Description] | |
26 | ||
27 | The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator | |
28 | while supplying an attribute of type `Transformed`. The supplied attribute gets created | |
29 | from the original attribute (of type `Exposed`) passed to this component using the | |
30 | customization point __customize_transform_attribute__. | |
31 | ||
32 | ||
33 | [heading Header] | |
34 | ||
35 | // forwards to <boost/spirit/home/karma/auxiliary/attr_cast.hpp> | |
36 | #include <boost/spirit/include/karma_attr_cast.hpp> | |
37 | ||
38 | Also, see __include_structure__. | |
39 | ||
40 | [heading Namespace] | |
41 | ||
42 | [table | |
43 | [[Name]] | |
44 | [[`boost::spirit::attr_cast // alias: boost::spirit::karma::attr_cast`]] | |
45 | ] | |
46 | ||
47 | [heading Synopsis] | |
48 | ||
49 | template <Exposed, Transformed> | |
50 | <unspecified> attr_cast(<unspecified>); | |
51 | ||
52 | [heading Template parameters] | |
53 | ||
54 | [table | |
55 | [[Parameter] [Description] [Default]] | |
56 | [[`Exposed`] [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]] | |
57 | [[`Transformed`][The type of the attribute expected by the embedded | |
58 | generator `g`.] [__unused_type__]] | |
59 | ] | |
60 | ||
61 | The `attr_cast` is a function template. It is possible to invoke it using the | |
62 | following schemes: | |
63 | ||
64 | attr_cast(g) | |
65 | attr_cast<Exposed>(g) | |
66 | attr_cast<Exposed, Transformed>(g) | |
67 | ||
68 | depending on which of the attribute types can be deduced properly if not | |
69 | explicitly specified. | |
70 | ||
71 | [heading Model of] | |
72 | ||
73 | [:__unary_generator_concept__] | |
74 | ||
75 | [variablelist Notation | |
76 | [[`g`] [A generator object.]] | |
77 | ] | |
78 | ||
79 | [heading Expression Semantics] | |
80 | ||
81 | Semantics of an expression is defined only where it differs from, or is | |
82 | not defined in __unary_generator_concept__. | |
83 | ||
84 | [table | |
85 | [[Expression] [Semantics]] | |
86 | [[`attr_cast(g)`] [Create a component invoking the | |
87 | generator `g` while passing an attribute of the type | |
88 | as normally expected by `g`. The type of the supplied | |
89 | attribute will be transformed to the type | |
90 | `g` exposes as its attribute type (by using the | |
91 | attribute customization point __customize_transform_attribute__). | |
92 | This generator does not fail unless `g` fails.]] | |
93 | [[`attr_cast<Exposed>(g)`] [Create a component invoking the | |
94 | generator `g` while passing an attribute of the type | |
95 | as normally expected by `g`. The supplied attribute | |
96 | is expected to be of the type `Exposed`, it will be | |
97 | transformed to the type `g` exposes as its attribute type | |
98 | (using the attribute customization point | |
99 | __customize_transform_attribute__). | |
100 | This generator does not fail unless `g` fails.]] | |
101 | [[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the | |
102 | generator `g` while passing an attribute of type | |
103 | `Transformed`. The supplied attribute is expected | |
104 | to be of the type `Exposed`, it will be transformed | |
105 | to the type `Transformed` (using the attribute | |
106 | customization point __customize_transform_attribute__). | |
107 | This generator does not fail unless `g` fails.]] | |
108 | ] | |
109 | ||
110 | [heading Attributes] | |
111 | ||
112 | [table | |
113 | [[Expression] [Attribute]] | |
114 | [[`attr_cast(g)`] [`g: A --> attr_cast(g): A`]] | |
115 | [[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]] | |
116 | [[`attr_cast<Exposed, Transformed>(g)`] | |
117 | [`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]] | |
118 | ] | |
119 | ||
120 | [heading Complexity] | |
121 | ||
122 | [:The complexity of this component is fully defined by the complexity of the | |
123 | embedded generator `g`.] | |
124 | ||
125 | [heading Example] | |
126 | ||
127 | [note The test harness for the example(s) below is presented in the | |
128 | __karma_basics_examples__ section.] | |
129 | ||
130 | Some includes: | |
131 | ||
132 | [reference_karma_includes] | |
133 | ||
134 | Some using declarations: | |
135 | ||
136 | [reference_karma_using_declarations_attr_cast] | |
137 | ||
138 | The example references data structure `int_data` which needs a specialization of | |
139 | the customization point __customize_transform_attribute__: | |
140 | ||
141 | [reference_karma_auxiliary_attr_cast_data1] | |
142 | ||
143 | Now we use the `attr_cast` pseudo generator to invoke the attribute | |
144 | transformation: | |
145 | ||
146 | [reference_karma_attr_cast1] | |
147 | ||
148 | [endsect] | |
149 | ||
150 | [/////////////////////////////////////////////////////////////////////////////] | |
151 | [section:eol End of Line Generator (`eol`)] | |
152 | ||
153 | [heading Description] | |
154 | ||
155 | The `eol` component generates a single newline character. It is equivalent | |
156 | to `lit('\n')` or simply '\\n' (please see the [karma_char `char_`] generator | |
157 | module for more details). | |
158 | ||
159 | [heading Header] | |
160 | ||
161 | // forwards to <boost/spirit/home/karma/auxiliary/eol.hpp> | |
162 | #include <boost/spirit/include/karma_eol.hpp> | |
163 | ||
164 | Also, see __include_structure__. | |
165 | ||
166 | [heading Namespace] | |
167 | ||
168 | [table | |
169 | [[Name]] | |
170 | [[`boost::spirit::eol // alias: boost::spirit::karma::eol`]] | |
171 | ] | |
172 | ||
173 | [heading Model of] | |
174 | ||
175 | [:__primitive_generator_concept__] | |
176 | ||
177 | [heading Expression Semantics] | |
178 | ||
179 | Semantics of an expression is defined only where it differs from, or is | |
180 | not defined in __primitive_generator_concept__. | |
181 | ||
182 | [table | |
183 | [[Expression] [Semantics]] | |
184 | [[`eol`] [Create a component generating a single end of line | |
185 | character in the output. This generator never fails | |
186 | (unless the underlying output stream reports an | |
187 | error).]] | |
188 | ] | |
189 | ||
190 | [heading Attributes] | |
191 | ||
192 | [table | |
193 | [[Expression] [Attribute]] | |
194 | [[`eol`] [__unused__]] | |
195 | ] | |
196 | ||
197 | [heading Complexity] | |
198 | ||
199 | [:O(1)] | |
200 | ||
201 | The complexity is constant as a single character is generated in the output. | |
202 | ||
203 | [heading Example] | |
204 | ||
205 | [note The test harness for the example(s) below is presented in the | |
206 | __karma_basics_examples__ section.] | |
207 | ||
208 | Some includes: | |
209 | ||
210 | [reference_karma_includes] | |
211 | ||
212 | Some using declarations: | |
213 | ||
214 | [reference_karma_using_declarations_eol] | |
215 | ||
216 | Basic usage of the `eol` generator: | |
217 | ||
218 | [reference_karma_eol] | |
219 | ||
220 | [endsect] | |
221 | ||
222 | [/////////////////////////////////////////////////////////////////////////////] | |
223 | [section:eps Epsilon Generator (`eps`)] | |
224 | ||
225 | The family of `eps` components allows to create pseudo generators generating | |
226 | an empty string. This feature is sometimes useful either to force a generator | |
227 | to fail or to succeed or to insert semantic actions into the generation process. | |
228 | ||
229 | [heading Description] | |
230 | ||
231 | The Epsilon (`eps`) is a multi-purpose generator that emits a zero length | |
232 | string. | |
233 | ||
234 | [heading Simple Form] | |
235 | ||
236 | In its simplest form, `eps` creates a component generating an empty string | |
237 | while always succeeding: | |
238 | ||
239 | eps // always emits a zero-length string | |
240 | ||
241 | This form is usually used to trigger a semantic action unconditionally. | |
242 | For example, it is useful in triggering error messages when a set of | |
243 | alternatives fail: | |
244 | ||
245 | r = a | b | c | eps[error()]; // Call error if a, b, and c fail to generate | |
246 | ||
247 | [heading Semantic Predicate] | |
248 | ||
249 | The `eps(b)` component generates an empty string as well, but | |
250 | succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)` | |
251 | is equivalent to `eps(b)` except it evaluates the supplied function `fb` at | |
252 | generate time, while using the return value as the criteria to succeed. | |
253 | ||
254 | Semantic predicates allow you to attach a conditional function anywhere | |
255 | in the grammar. In this role, the epsilon takes a __karma_lazy_argument__ that | |
256 | returns `true` or `false`. The __karma_lazy_argument__ is typically a test | |
257 | that is called to resolve ambiguity in the grammar. A generator failure will | |
258 | be reported when the __karma_lazy_argument__ result evaluates to `false`. | |
259 | Otherwise an empty string will be emitted. The general form is: | |
260 | ||
261 | eps_p(fb) << rest; | |
262 | ||
263 | The __karma_lazy_argument__ `fb` is called to do a semantic test. If the test | |
264 | returns true, `rest` will be evaluated. Otherwise, the production will return | |
265 | early without ever touching rest. | |
266 | ||
267 | [heading Header] | |
268 | ||
269 | // forwards to <boost/spirit/home/karma/auxiliary/eps.hpp> | |
270 | #include <boost/spirit/include/karma_eps.hpp> | |
271 | ||
272 | Also, see __include_structure__. | |
273 | ||
274 | [heading Namespace] | |
275 | ||
276 | [table | |
277 | [[Name]] | |
278 | [[`boost::spirit::eps // alias: boost::spirit::karma::eps`]] | |
279 | ] | |
280 | ||
281 | [heading Model of] | |
282 | ||
283 | [:__primitive_generator_concept__] | |
284 | ||
285 | [variablelist Notation | |
286 | [[`b`] [A boolean value.]] | |
287 | [[`fb`] [A __karma_lazy_argument__ that evaluates to a boolean value.]] | |
288 | ] | |
289 | ||
290 | [heading Expression Semantics] | |
291 | ||
292 | Semantics of an expression is defined only where it differs from, or is | |
293 | not defined in __primitive_generator_concept__. | |
294 | ||
295 | [table | |
296 | [[Expression] [Semantics]] | |
297 | [[`eps`] [Creates a component generating an empty string. | |
298 | Succeeds always.]] | |
299 | [[`eps(b)`] [Creates a component generating an empty string. | |
300 | Succeeds if `b` is `true` (unless the underlying | |
301 | output stream reports an error).]] | |
302 | [[`eps(fb)`] [Creates a component generating an empty string. | |
303 | Succeeds if `fb` returns `true` at generate time | |
304 | (unless the underlying output stream reports an | |
305 | error).]] | |
306 | ] | |
307 | ||
308 | [heading Attributes] | |
309 | ||
310 | [table | |
311 | [[Expression] [Attribute]] | |
312 | [[`eps`] [__unused__]] | |
313 | [[`eps(b)`] [__unused__]] | |
314 | [[`eps(fb)`] [__unused__]] | |
315 | ] | |
316 | ||
317 | [heading Complexity] | |
318 | ||
319 | [:O(1)] | |
320 | ||
321 | The complexity is constant as no output is generated. | |
322 | ||
323 | [heading Example] | |
324 | ||
325 | [note The test harness for the example(s) below is presented in the | |
326 | __karma_basics_examples__ section.] | |
327 | ||
328 | Some includes: | |
329 | ||
330 | [reference_karma_includes] | |
331 | ||
332 | Some using declarations: | |
333 | ||
334 | [reference_karma_using_declarations_eps] | |
335 | ||
336 | Basic usage of the `eps` generator: | |
337 | ||
338 | [reference_karma_eps] | |
339 | ||
340 | [endsect] | |
341 | ||
342 | [/////////////////////////////////////////////////////////////////////////////] | |
343 | [section:lazy Lazy Generator (`lazy`)] | |
344 | ||
345 | [heading Description] | |
346 | ||
347 | The family of `lazy` components allows to use a dynamically returned generator | |
348 | component for output generation. It calls the provided function or function | |
349 | object at generate time using its return value as the actual generator to | |
350 | produce the output. | |
351 | ||
352 | [heading Header] | |
353 | ||
354 | // forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp> | |
355 | #include <boost/spirit/include/karma_lazy.hpp> | |
356 | ||
357 | Also, see __include_structure__. | |
358 | ||
359 | [heading Namespace] | |
360 | ||
361 | [table | |
362 | [[Name]] | |
363 | [[`boost::spirit::lazy // alias: boost::spirit::karma::lazy`]] | |
364 | ] | |
365 | ||
366 | [heading Model of] | |
367 | ||
368 | [:__generator_concept__] | |
369 | ||
370 | [variablelist Notation | |
371 | [[`fg`] [A function or function object that evaluates to a generator | |
372 | object (an object exposing the __generator_concept__). This | |
373 | function will be invoked at generate time.]] | |
374 | ] | |
375 | ||
376 | The signature of `fg` is expected to be | |
377 | ||
378 | G f(Unused, Context) | |
379 | ||
380 | where `G`, the function's return value, is the type of the generator to be | |
381 | invoked, and `Context` is the generator's __karma_context__ type (The | |
382 | first argument is __unused__ to make the `Context` the second argument. This | |
383 | is done for uniformity with __karma_actions__). | |
384 | ||
385 | [heading Expression Semantics] | |
386 | ||
387 | Semantics of an expression is defined only where it differs from, or is | |
388 | not defined in __generator_concept__. | |
389 | ||
390 | [table | |
391 | [[Expression] [Semantics]] | |
392 | [[`fg`] [The __boost_phoenix__ function object `fg` will be | |
393 | invoked at generate time. It is expected to return a | |
394 | generator instance. This generator is then invoked | |
395 | in order to generate the output. This generator will | |
396 | succeed as long as the invoked generated succeeds as | |
397 | well (unless the underlying output stream reports | |
398 | an error).]] | |
399 | [[`lazy(fg)`] [The function or function object will be invoked at | |
400 | generate time. It is expected to return a generator | |
401 | instance (note this version of `lazy` does not | |
402 | require `fg` to be a __boost_phoenix__ function | |
403 | object). This generator is then invoked in order to | |
404 | generate the output. This generator will succeed as | |
405 | long as the invoked generated succeeds as well (except | |
406 | if the underlying output stream reports an error).]] | |
407 | ] | |
408 | ||
409 | [heading Attributes] | |
410 | ||
411 | [table | |
412 | [[Expression] [Attribute]] | |
413 | [[`fg`] [The attribute type `G` as exposed by the generator `g` | |
414 | returned from `fg`.]] | |
415 | [[`lazy(fg)`] [The attribute type `G` as exposed by the generator `g` | |
416 | returned from `fg`.]] | |
417 | ] | |
418 | ||
419 | [heading Complexity] | |
420 | ||
421 | The complexity of the `lazy` component is determined by the complexity of the | |
422 | generator returned from `fg`. | |
423 | ||
424 | [heading Example] | |
425 | ||
426 | [note The test harness for the example(s) below is presented in the | |
427 | __karma_basics_examples__ section.] | |
428 | ||
429 | Some includes: | |
430 | ||
431 | [reference_karma_includes] | |
432 | ||
433 | Some using declarations: | |
434 | ||
435 | [reference_karma_using_declarations_lazy] | |
436 | ||
437 | Basic usage of the `lazy` generator: | |
438 | ||
439 | [reference_karma_lazy] | |
440 | ||
441 | [endsect] | |
442 | ||
443 | [endsect] |