]> git.proxmox.com Git - ceph.git/blame - ceph/src/boost/libs/spirit/doc/karma/quick_reference.qbk
projects / ceph.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / spirit / doc / karma / quick_reference.qbk
CommitLineData
7c673cae
FG		 1[/==============================================================================
2 Copyright (C) 2001-2011 Joel de Guzman
3 Copyright (C) 2001-2011 Hartmut Kaiser
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
9This quick reference section is provided for convenience. You can use
10this section as sort of a "cheat-sheet" on the most commonly used Karma
11components. It is not intended to be complete, but should give you an
12easy way to recall a particular component without having to dig up on
13pages upon pages of reference documentation.
14
15[/////////////////////////////////////////////////////////////////////////////]
16[section Common Notation]
17
18[variablelist Notation
19 [[`G`] [Generator type]]
20 [[`g, a, b, c, d`] [Generator objects]]
21 [[`A, B, C, D`] [Attribute types of generators `a`, `b`, `c`, and `d`]]
22 [[`I`] [The iterator type used for generation]]
23 [[`Unused`] [An `unused_type`]]
24 [[`Context`] [The enclosing rule's `Context` type]]
25 [[`attrib`] [An attribute value]]
26 [[`Attrib`] [An attribute type]]
27 [[`b`] [A boolean expression]]
28 [[`B`] [A type to be interpreted in boolean expressions]]
29 [[`fg`] [A (lazy generator) function with signature `G(Unused, Context)`]]
30 [[`fa`] [A (semantic action) function with signature `void(Attrib&, Context, bool&)`.
31 The third parameter is a boolean flag that can be set to false to
32 force the generator to fail. Both `Context` and the boolean flag are
33 optional.]]
34 [[`outiter`] [An output iterator to receive the generated output]]
35 [[`Ch`] [Character-class specific character type (See __char_class_types__)]]
36 [[`ch, ch2`] [Character-class specific character (See __char_class_types__)]]
37 [[`charset`] [Character-set specifier string (example: `"a-z0-9"`)]]
38 [[`str`] [Character-class specific string (See __char_class_types__)]]
39 [[`Str`] [Attribute of `str`: `std::basic_string<T>` where `T` is the underlying character type of `str`]]
40 [[`num`] [Numeric literal, any integer or real number type]]
41 [[`Num`] [Attribute of `num`: any integer or real number type]]
42 [[`tuple<>`] [Used as a placeholder for a fusion sequence]]
43 [[`vector<>`] [Used as a placeholder for an STL container]]
44 [[`variant<>`] [Used as a placeholder for a boost::variant]]
45 [[`optional<>`] [Used as a placeholder for a boost::optional]]
46]
47
48[endsect]
49
50[/////////////////////////////////////////////////////////////////////////////]
51[section:primitive_generators Karma Generators]
52
53[section:char Character Generators]
54
55See here for more information about __karma_char__.
56
57[table
58 [[Expression] [Attribute] [Description]]
59 [[[karma_char `ch`]] [`Unused`] [Generate `ch`]]
60 [[[karma_char `lit(ch)`]] [`Unused`] [Generate `ch`]]
61
62 [[[karma_char `char_`]] [`Ch`] [Generate character supplied as the attribute]]
63 [[[karma_char `char_(ch)`]] [`Ch`] [Generate `ch`,
64 if an attribute is supplied it must match]]
65 [[[karma_char `char_("c")`]] [`Ch`] [Generate a single char string literal, `c`,
66 if an attribute is supplied it must match]]
67 [[[karma_char `char_(ch, ch2)`]][`Ch`] [Generate the character supplied as the attribute,
68 if it belongs to the character range from
69 `ch` to `ch2`]]
70 [[[karma_char `char_(charset)`]][`Ch`] [Generate the character supplied as the attribute,
71 if it belongs to the character set `charset`]]
72
73 [[[karma_char_class `alnum`]] [`Ch`] [Generate the character supplied as the attribute
74 if it satisfies the concept of `std::isalnum` in
75 the character set defined by `NS`]]
76 [[[karma_char_class `alpha`]] [`Ch`] [Generate the character supplied as the attribute
77 if it satisfies the concept of `std::isalpha` in
78 the character set defined by `NS`]]
79 [[[karma_char_class `blank`]] [`Ch`] [Generate the character supplied as the attribute
80 if it satisfies the concept of `std::isblank` in
81 the character set defined by `NS`]]
82 [[[karma_char_class `cntrl`]] [`Ch`] [Generate the character supplied as the attribute
83 if it satisfies the concept of `std::iscntrl` in
84 the character set defined by `NS`]]
85 [[[karma_char_class `digit`]] [`Ch`] [Generate the character supplied as the attribute
86 if it satisfies the concept of `std::isdigit` in
87 the character set defined by `NS`]]
88 [[[karma_char_class `graph`]] [`Ch`] [Generate the character supplied as the attribute
89 if it satisfies the concept of `std::isgraph` in
90 the character set defined by `NS`]]
91 [[[karma_char_class `print`]] [`Ch`] [Generate the character supplied as the attribute
92 if it satisfies the concept of `std::isprint` in
93 the character set defined by `NS`]]
94 [[[karma_char_class `punct`]] [`Ch`] [Generate the character supplied as the attribute
95 if it satisfies the concept of `std::ispunct` in
96 the character set defined by `NS`]]
97 [[[karma_char_class `space`]] [`Ch`] [Generate the character supplied as the attribute
98 if it satisfies the concept of `std::isspace`, or
99 a single space character in the character set
100 defined by `NS`]]
101 [[[karma_char_class `xdigit`]] [`Ch`] [Generate the character supplied as the attribute
102 if it satisfies the concept of `std::isxdigit` in
103 the character set defined by `NS`]]
104 [[[karma_char_class `lower`]] [`Ch`] [Generate the character supplied as the attribute
105 if it satisfies the concept of `std::islower` in
106 the character set defined by `NS`]]
107 [[[karma_char_class `upper`]] [`Ch`] [Generate the character supplied as the attribute
108 if it satisfies the concept of `std::isupper` in
109 the character set defined by `NS`]]
110]
111
112[endsect]
113
114[section:string String Generators]
115
116See here for more information about [karma_string String Generators].
117
118[table
119 [[Expression] [Attribute] [Description]]
120 [[[karma_string `str`]] [`Unused`] [Generate `str`]]
121 [[[karma_string `lit(str)`]] [`Unused`] [Generate `str`]]
122 [[[karma_string `string`]] [`Str`] [Generate string supplied as the attribute]]
123 [[[karma_string `string(str)`]] [`Str`] [Generate `str`,
124 if an attribute is supplied it must match]]
125
126 [[[karma_symbols `symbols<Attr, T>`]][`Attr`] [Declare a symbol table, `sym`. `Attr` is the
127 The type of the original attribute to be used
128 as the key into the symbol generator.
129 `T` is the data type associated with each key.]]
130 [[
131``
132 sym.add
133 (attr1, val1)
134 (attr2, val2)
135 /*...more...*/
136 ;
137``
138 ]
139 [N/A] [Add symbols into a symbol table, `sym`.
140 val1 and val2 are optional data of type `T`,
141 the data type associated with each key.]]
142 [[`sym`] [`T`] [Emits entries in the symbol table, `sym`. If
143 attribute is found in the symbol table,
144 the corresponding value is emitted. If `sym`
145 does not store values, the original attribute
146 is emitted.]]
147]
148
149[endsect]
150
151[section:real_number Real Number Generators]
152
153See here for more information about __karma_numeric__.
154
155[table
156 [[Expression] [Attribute] [Description]]
157 [[[real_number `lit(num)`]] [`Unused`] [Generate `num`]]
158 [[[real_number `float_`]] [`float`] [Generate a real number from a `float`]]
159 [[[real_number `float_(num)`]] [`float`] [Generate `num` as a real number from a `float`,
160 if an attribute is supplied it must match `num`]]
161 [[[real_number `double_`]] [`double`] [Generate a real number from a `double`]]
162 [[[real_number `double_(num)`]] [`double`] [Generate a `num` as a real number from a `double`,
163 if an attribute is supplied it must match `num`]]
164 [[[real_number `long_double`]] [`long double`] [Generate a real number from a `long double`]]
165 [[[real_number `long_double(num)`]] [`long double`] [Generate `num` as a real number from a `long double`,
166 if an attribute is supplied it must match `num`]]
167
168 [[[real_number ``real_generator<
169 Num, Policies
170>()``]]
171 [`Num`] [Generate a real number `Num` using
172 the supplied real number formatting policies]]
173 [[[real_number ``real_generator<
174 Num, Policies
175>()(num)``]]
176 [`Num`] [Generate real number `num` as a `Num`
177 using the supplied real number formatting
178 policies, if an attribute is supplied it must
179 match]]
180]
181
182[endsect]
183
184[section:signed_int Integer Generators]
185
186[table
187 [[Expression] [Attribute] [Description]]
188 [[[signed_int `lit(num)`]] [`Unused`] [Generate `num`]]
189 [[[signed_int `short_`]] [`short`] [Generate a short integer]]
190 [[[signed_int `short_(num)`]] [`short`] [Generate `num` as a short integer,
191 if an attribute is supplied it must match]]
192 [[[signed_int `int_`]] [`int`] [Generate an int]]
193 [[[signed_int `int_(num)`]] [`int`] [Generate `num` as an int,
194 if an attribute is supplied it must match]]
195 [[[signed_int `long_`]] [`long`] [Generate a long integer]]
196 [[[signed_int `long_(num)`]] [`long`] [Generate `num` as long integer,
197 if an attribute is supplied it must match]]
198 [[[signed_int `long_long`]] [`long long`] [Generate a long long]]
199 [[[signed_int `long_long(num)`]] [`long long`] [Generate `num` as a long long,
200 if an attribute is supplied it must match]]
201
202 [[[signed_int ``int_generator<
203 Num, Radix, force_sign
204>()``]]
205 [`Num`] [Generate a `Num`]]
206 [[[signed_int ``int_generator<
207 Num, Radix, force_sign
208>()(num)``]]
209 [`Num`] [Generate a `num` as a `Num`,
210 if an attribute is supplied it must match]]
211]
212
213[endsect]
214
215[section:unsigned_int Unsigned Integer Generators]
216
217[table
218 [[Expression] [Attribute] [Description]]
219 [[[unsigned_int `lit(num)`]] [`Unused`] [Generate `num`]]
220 [[[unsigned_int `ushort_`]] [`unsigned short`] [Generate an unsigned short integer]]
221 [[[unsigned_int `ushort_(num)`]] [`unsigned short`] [Generate `num` as an unsigned short integer,
222 if an attribute is supplied it must match]]
223 [[[unsigned_int `uint_`]] [`unsigned int`] [Generate an unsigned int]]
224 [[[unsigned_int `uint_(num)`]] [`unsigned int`] [Generate `num` as an unsigned int,
225 if an attribute is supplied it must match]]
226 [[[unsigned_int `ulong_`]] [`unsigned long`] [Generate an unsigned long integer]]
227 [[[unsigned_int `ulong_(num)`]] [`unsigned long`] [Generate `num` as an unsigned long integer,
228 if an attribute is supplied it must match]]
229 [[[unsigned_int `ulong_long`]] [`unsigned long long`] [Generate an unsigned long long]]
230 [[[unsigned_int `ulong_long(num)`]] [`unsigned long long`] [Generate `num` as an unsigned long long,
231 if an attribute is supplied it must match]]
232 [[[unsigned_int `bin`]] [`unsigned int`] [Generate a binary integer from an `unsigned int`]]
233 [[[unsigned_int `oct`]] [`unsigned int`] [Generate an octal integer from an `unsigned int`]]
234 [[[unsigned_int `hex`]] [`unsigned int`] [Generate a hexadecimal integer from an `unsigned int`]]
235
236 [[[unsigned_int ``uint_generator<
237 Num, Radix
238>()``]]
239 [`Num`] [Generate an unsigned `Num`]]
240 [[[unsigned_int ``uint_generator<
241 Num, Radix
242>()(num)``]]
243 [`Num`] [Generate an unsigned `num` as a `Num`,
244 if an attribute is supplied it must match]]
245]
246
247[endsect]
248
249[section:boolean Boolean Generators]
250
251[table
252 [[Expression] [Attribute] [Description]]
253 [[[boolean `lit(num)`]] [`Unused`] [Generate `num`]]
254 [[[boolean `bool_`]] [`bool`] [Generate a boolean]]
255 [[[boolean `bool_(b)`]] [`bool`] [Generate `b` as a boolean,
256 if an attribute is supplied it must match]]
257 [[[boolean ``bool_generator<
258 B, Policies
259>()``]]
260 [`B`] [Generate a boolean of type `B`]]
261 [[[boolean ``bool_generator<
262 B, Policies
263>()(b)``]]
264 [`B`] [Generate a boolean `b` as a `B`,
265 if an attribute is supplied it must match]]
266]
267
268[endsect]
269
270[section:stream Stream Generators]
271
272See here for more information about [karma_stream Stream Generators].
273
274[table
275 [[Expression] [Attribute] [Description]]
276 [[[karma_stream `stream`]] [`hold_any`] [Generate narrow character (`char`) based output
277 using the matching streaming `operator<<()`]]
278 [[[karma_stream `stream(s)`]] [`Unused`] [Generate narrow character (`char`) based output
279 from the immediate argument `s` using the matching
280 streaming `operator<<()`]]
281 [[[karma_stream `wstream`]] [`whold_any`] [Generate wide character (`wchar_t`) based output
282 using the matching streaming `operator<<()`]]
283 [[[karma_stream `wstream(s)`]] [`Unused`] [Generate wide character (`wchar_t`) based output
284 from the immediate argument `s` using the matching
285 streaming `operator<<()`]]
286 [
287[[karma_stream ``stream_generator<
288 Char
289>()``]] [`basic_hold_any<Char>`] [Generate output based on the given character type
290 (`Char`) using the matching streaming `operator<<()`]]
291 [
292[[karma_stream ``stream_generator<
293 Char
294>()(s)``]] [`Unused`] [Generate output based on the given character type
295 `Char` from the immediate argument `s` using the
296 matching streaming `operator<<()`]]
297]
298
299[endsect]
300
301[section:binary Binary Generators]
302
303See here for more information about __karma_binary__.
304
305[table
306 [[Expression] [Attribute] [Description]]
307 [[[karma_native_binary `byte_`]] [8 bits native endian] [Generate an 8 bit binary]]
308 [[[karma_native_binary `word`]] [16 bits native endian] [Generate a 16 bit binary in native endian representation]]
309 [[[karma_big_binary `big_word`]] [16 bits big endian] [Generate a 16 bit binary in big endian representation]]
310 [[[karma_little_binary `little_word`]] [16 bits little endian] [Generate a 16 bit binary in little endian representation]]
311 [[[karma_native_binary `dword`]] [32 bits native endian] [Generate a 32 bit binary in native endian representation]]
312 [[[karma_big_binary `big_dword`]] [32 bits big endian] [Generate a 32 bit binary in big endian representation]]
313 [[[karma_little_binary `little_dword`]][32 bits little endian] [Generate a 32 bit binary in little endian representation]]
314 [[[karma_native_binary `qword`]] [64 bits native endian] [Generate a 64 bit binary in native endian representation]]
315 [[[karma_big_binary `big_qword`]] [64 bits big endian] [Generate a 64 bit binary in big endian representation]]
316 [[[karma_little_binary `little_qword`]][64 bits little endian] [Generate a 64 bit binary in little endian representation]]
317 [[`pad(num)`] [`Unused`] [Generate additional null bytes allowing to align generated
318 output with memory addresses divisible by `num`.]]
319]
320
321[endsect]
322
323[section:auxiliary Auxiliary Generators]
324
325See here for more information about __karma_auxiliary__.
326
327[table
328 [[Expression] [Attribute] [Description]]
329 [[[karma_attr_cast `attr_cast<Exposed>(a)`]] [`Exposed`] [Invoke `a` while supplying an attribute of type `Exposed`.]]
330 [[__karma_eol__] [`Unused`] [Generate the end of line (`\n`)]]
331 [[__karma_eps__] [`Unused`] [Generate an empty string]]
332 [[__karma_feps__] [`Unused`] [If `b` is true, generate an empty string]]
333 [[[karma_lazy `lazy(fg)`]]
334 [Attribute of `G` where `G`
335 is the return type of `fg`] [Invoke `fg` at generation time, returning a generator
336 `g` which is then called to generate.]]
337 [[[karma_lazy `fg`]] [see [karma_lazy `lazy(fg)`] above] [Equivalent to [karma_lazy `lazy(fg)`]]]
338]
339
340[endsect]
341
342[section:auto Auto Generators]
343
344See here for more information about [karma_auto Auto Generators].
345
346[table
347 [[Expression] [Attribute] [Description]]
348 [[[karma_auto `auto_`]] [`hold_any`] [Generate output using a generator
349 created from the supplied attribute type
350 using the __create_generator__ API function.]]
351]
352
353[endsect]
354
355[/////////////////////////////////////////////////////////////////////////////]
356[section:operators Generator Operators]
357
358See here for more information about __karma_operator__.
359
360[table
361 [[Expression] [Attribute] [Description]]
362 [[[link spirit.karma.reference.operator.not_predicate `!a`]]
363 [`A`] [Not predicate. Ensure that `a` does not succeed
364 generating, but don't create any output]]
365 [[[link spirit.karma.reference.operator.not_predicate `&a`]]
366 [`A`] [And predicate. Ensure that `a` does succeed
367 generating, but don't create any output]]
368 [[[link spirit.karma.reference.operator.optional `-a`]]
369 [`optional<A>`] [Optional. Generate `a` zero or one time]]
370 [[[link spirit.karma.reference.operator.kleene `*a`]]
371 [`vector<A>`] [Kleene. Generate `a` zero or more times]]
372 [[[link spirit.karma.reference.operator.plus `+a`]]
373 [`vector<A>`] [Plus. Generate `a` one or more times]]
374 [[[link spirit.karma.reference.operator.alternative `a | b`]]
375 [`variant<A, B>`] [Alternative. Generate `a` or `b`]]
376 [[[link spirit.karma.reference.operator.sequence `a << b`]]
377 [`tuple<A, B>`] [Sequence. Generate `a` followed by `b`]]
378 [[[link spirit.karma.reference.operator.list `a % b`]]
379 [`vector<A>`] [List. Generate `a` delimited `b` one or more times]]
380]
381
382[:For more information about the attribute propagation rules implemented by the
383compound generators please see __sec_karma_compound__.]
384
385[endsect]
386
387[/////////////////////////////////////////////////////////////////////////////]
388[section:directives Generator Directives]
389
390See here for more information about __karma_directive__.
391
392[table
393 [[Expression] [Attribute] [Description]]
394 [[[karma_upperlower `lower`]`[a]`] [`A`] [Generate `a` as lower case]]
395 [[[karma_upperlower `upper`]`[a]`] [`A`] [Generate `a` as upper case]]
396
397 [[[karma_align `left_align`]`[a]`] [`A`] [Generate `a` left aligned in column of width
398 `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
399 [[[karma_align `left_align`]`(num)[a]`] [`A`] [Generate `a` left aligned in column of width `num`]]
400 [[[karma_align `left_align`]`(g)[a]`] [`A`] [Generate `a` left aligned in column of width
401 `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
402 generate the necessary padding]]
403 [[[karma_align `left_align`]`(num, g)[a]`][`A`] [Generate `a` left aligned in column of width `num`
404 while using `g` to generate the necessary
405 padding]]
406
407 [[[karma_align `center`]`[a]`] [`A`] [Generate `a` centered in column of width
408 `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
409 [[[karma_align `center`]`(num)[a]`] [`A`] [Generate `a` centered in column of width `num`]]
410 [[[karma_align `center`]`(g)[a]`] [`A`] [Generate `a` centered in column of width
411 `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
412 generate the necessary padding]]
413 [[[karma_align `center`]`(num, g)[a]`] [`A`] [Generate `a` centered in column of width `num`
414 while using `g` to generate the necessary
415 padding]]
416
417 [[[karma_align `right_align`]`[a]`] [`A`] [Generate `a` right aligned in column of width
418 `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]]
419 [[[karma_align `right_align`]`(num)[a]`] [`A`] [Generate `a` right aligned in column of width `num`]]
420 [[[karma_align `right_align`]`(g)[a]`] [`A`] [Generate `a` right aligned in column of width
421 `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to
422 generate the necessary padding]]
423 [[[karma_align `right_align`]`(num, g)[a]`][`A`][Generate `a` right aligned in column of width `num`
424 while using `g` to generate the necessary
425 padding]]
426
427 [[[karma_maxwidth `maxwidth`]`[a]`] [`A`] [Generate `a` truncated to column of width
428 `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`]]
429 [[[karma_maxwidth `maxwidth`]`(num)[a]`] [`A`] [Generate `a` truncated to column of width `num`]]
430
431 [[[karma_repeat `repeat`]`[a]`] [`vector<A>`] [Repeat `a` zero or more times]]
432 [[[karma_repeat `repeat`]`(num)[a]`] [`vector<A>`] [Repeat `a` `num` times]]
433 [[[karma_repeat `repeat`]`(num1, num2)[a]`] [`vector<A>`] [Repeat `a` `num1` to `num2` times]]
434 [[[karma_repeat `repeat`]`(num, inf)[a]`] [`vector<A>`] [Repeat `a` `num` or more times]]
435
436 [[__karma_verbatim__`[a]`][`A`] [Disable delimited generation for `a`. Performs post delimiting.]]
437 [[[karma_delimit `delimit`]`[a]`] [`A`] [Reestablish the delimiter that got inhibited by verbatim]]
438 [[[karma_delimit `delimit`]`(d)[a]`] [`A`] [Use `d` as a delimiter for generating `a`]]
439 [[[karma_no_delimit `no_delimit`]`[a]`] [`A`] [Disable delimited generation for `a`. No post-delimiting step performed.]]
440
441 [[__karma_as__`()[a]`] [`A`] [Force atomic output from arbitrary attribute types]]
442 [[__karma_as_string__`[a]`] [`A`] [Force atomic output from string attributes]]
443 [[__karma_as_wstring__`[a]`] [`A`] [Force atomic output from wide character string attributes]]
444
445 [[__karma_omit__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything.
446 The embedded generator will be always executed.]]
447 [[__karma_skip__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything.
448 The embedded generator will never be executed.]]
449
450 [[__karma_duplicate__`[a]`] [`A`] [The supplied attribute will be duplicated and passed unchanged to
451 all embedded elements of a sequence.]]
452
453 [[__karma_buffer__`[a]`][`A`] [Temporarily intercept the output generated by `a`,
454 flushing it only after `a` succeeded]]
455
456 [[[karma_columns `columns`]`[a]`] [`A`] [Generate `a` split into
457 `BOOST_KARMA_DEFAULT_COLUMNS` number of columns using
458 `karma::eol` as column delimiter]]
459 [[[karma_columns `columns`]`(num)[a]`] [`A`] [Generate `a` split into
460 `num` number of columns using
461 `karma::eol` as column delimiter]]
462 [[[karma_columns `columns`]`(g)[a]`] [`A`] [Generate `a` split into
463 `BOOST_KARMA_DEFAULT_COLUMNS` number of columns using
464 `g` as column delimiter]]
465 [[[karma_columns `columns`]`(num, g)[a]`][`A`][Generate `a` split into
466 `num` number of columns using
467 `g` as column delimiter]]
468]
469
470[endsect]
471
472[section:action Generator Semantic Actions]
473
474[table
475 [[Expression] [Attribute] [Description]]
476 [[`g[fa]`] [Attribute of `g`] [Call semantic action `fa` before invoking `g`]]
477]
478
479[endsect]
480
481[endsect]
482
483[/////////////////////////////////////////////////////////////////////////////]
484[section Compound Attribute Rules]
485
486[heading Notation]
487
488The notation we use is of the form:
489
490 a: A, b: B, ... --> composite-expression: composite-attribute
491
492`a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's
493attribute types. `composite-expression` is the expression involving the
494operands and `composite-attribute` is the resulting attribute type of
495the composite expression.
496
497For instance:
498
499 a: A, b: B --> (a << b): tuple<A, B>
500
501which reads as: given, `a` and `b` are generators, and `A` is the type
502of the attribute of `a`, and `B` is the type of the attribute of `b`, then the
503type of the attribute of `a << b` will be `tuple<A, B>`.
504
505[important In the attribute tables, we will use `vector<A>` and
506`tuple<A, B...>` as placeholders only. The notation of `vector<A>`
507stands for ['any __stl__ container] holding elements of type `A` and the
508notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding
509`A`, `B`, ... etc. elements. The notation of `variant<A, B, ...>` stands for
510['a __boost_variant__] capable of holding `A`, `B`, ... etc. elements. Finally,
511`Unused` stands for __unused_type__. ]
512
513[heading Compound Generator Attribute Types]
514
515[table
516 [[Expression] [Attribute]]
517
518 [[__karma_sequence__ (`a << b`)]
519[``a: A, b: B --> (a << b): tuple<A, B>
520a: A, b: Unused --> (a << b): A
521a: Unused, b: B --> (a << b): B
522a: Unused, b: Unused --> (a << b): Unused
523
524a: A, b: A --> (a << b): vector<A>
525a: vector<A>, b: A --> (a << b): vector<A>
526a: A, b: vector<A> --> (a << b): vector<A>
527a: vector<A>, b: vector<A> --> (a << b): vector<A>``]]
528
529 [[__karma_alternative__ (`a | b`)]
530[``a: A, b: B --> (a | b): variant<A, B>
531a: A, b: Unused --> (a | b): A
532a: Unused, b: B --> (a | b): B
533a: Unused, b: Unused --> (a | b): Unused
534a: A, b: A --> (a | b): A``]]
535
536 [[[karma_kleene Kleene (`*a`)]]
537[``a: A --> *a: vector<A>
538a: Unused --> *a: Unused``]]
539 [[__karma_plus__ (`+a`)]
540[``a: A --> +a: vector<A>
541a: Unused --> +a: Unused``]]
542
543 [[__karma_list__ (`a % b`)]
544[``a: A, b: B --> (a % b): vector<A>
545a: Unused, b: B --> (a % b): Unused``]]
546
547 [[[karma_repeat Repetition] (`repeat[]`)]
548[``a: A --> repeat(...,...)[a]: vector<A>
549a: Unused --> repeat(...,...)[a]: Unused``]]
550
551 [[__karma_optional__ (`-a`)]
552[``a: A --> -a: optional<A>
553a: Unused --> -a: Unused``]]
554
555 [[__karma_and_predicate__ (`&a`)] [`a: A --> &a: A`]]
556 [[__karma_not_predicate__ (`!a`)] [`a: A --> !a: A`]]
557]
558
559[endsect]
560
561[/////////////////////////////////////////////////////////////////////////////]
562[section:non_terminals Nonterminals]
563
564See here for more information about __karma_nonterminal__.
565
566[variablelist Notation
567 [[`RT`] [Synthesized attribute. The rule or grammar's return type.]]
568 [[`Arg1`, `Arg2`, `ArgN`] [Inherited attributes. Zero or more arguments.]]
569 [[`L1`, `L2`, `LN`] [Zero or more local variables.]]
570 [[`r, r2`] [Rules]]
571 [[`g`] [A grammar]]
572 [[`p`] [A generator expression]]
573 [[`my_grammar`] [A user defined grammar]]
574]
575
576[variablelist Terminology
577 [[Signature] [`RT(Arg1, Arg2, ... ,ArgN)`. The signature specifies
578 the synthesized (return value) and inherited (arguments)
579 attributes.]]
580 [[Locals] [`locals<L1, L2, ..., LN>`. The local variables.]]
581 [[Delimiter] [The delimit-generator type]]
582]
583
584[variablelist Template Arguments
585 [[`Iterator`] [The iterator type you will use for parsing.]]
586 [[`A1`, `A2`, `A3`] [Can be one of 1) Signature 2) Locals 3) Delimiter.]]
587]
588
589[table
590 [[Expression] [Description]]
591 [[`rule<OutputIterator, A1, A2, A3> r(name);`] [Rule declaration. `OutputIterator` is required.
592 `A1, A2, A3` are optional and can be specified in any order.
593 `name` is an optional string that gives the rule
594 its name, useful for debugging.]]
595 [[`rule<OutputIterator, A1, A2, A3> r(r2);`] [Copy construct rule `r` from rule `r2`.]]
596 [[`r = r2;`] [Assign rule `r2` to `r`. `boost::shared_ptr` semantics.]]
597 [[`r.alias()`] [Return an alias of `r`. The alias is a generator that
598 holds a reference to `r`. Reference semantics.]]
599 [[`r.copy()`] [Get a copy of `r`.]]
600 [[`r.name(name)`] [Set the name of a rule]]
601 [[`r.name()`] [Get the name of a rule]]
602 [[debug(r)] [Debug rule `r`]]
603 [[`r = g;`] [Rule definition]]
604 [[`r %= g;`] [Auto-rule definition. The attribute of `g` should be
605 compatible with the synthesized attribute of `r`. When `g`
606 is successful, its attribute is automatically propagated
607 to `r`'s synthesized attribute.]]
608
609 [[
610``
611 template <typename OutputIterator>
612 struct my_grammar : grammar<OutputIterator, A1, A2, A3>
613 {
614 my_grammar() : my_grammar::base_type(start, name)
615 {
616 // Rule definitions
617 start = /* ... */;
618 }
619
620 rule<OutputIterator, A1, A2, A3> start;
621 // more rule declarations...
622 };
623``
624 ] [Grammar definition. `name` is an optional string that gives the
625 grammar its name, useful for debugging.]]
626 [[my_grammar<OutputIterator> g] [Instantiate a grammar]]
627 [[`g.name(name)`] [Set the name of a grammar]]
628 [[`g.name()`] [Get the name of a grammar]]
629]
630
631[endsect]
632
633[/////////////////////////////////////////////////////////////////////////////]
634[section:semantic_actions Generator Semantic Actions]
635
636Semantic Actions may be attached to any generator as follows:
637
638 g[f]
639
640where `f` is a function with the signatures:
641
642 void f(Attrib&);
643 void f(Attrib&, Context&);
644 void f(Attrib&, Context&, bool&);
645
646You can use __boost_bind__ to bind member functions. For function
647objects, the allowed signatures are:
648
649 void operator()(Attrib&, unused_type, unused_type) const;
650 void operator()(Attrib&, Context&, unused_type) const;
651 void operator()(Attrib&, Context&, bool&) const;
652
653The `unused_type` is used in the signatures above to signify 'don't
654care'.
655
656For more information see __karma_actions__.
657
658[endsect]
659
660[/////////////////////////////////////////////////////////////////////////////]
661[section Phoenix]
662
663__boost_phoenix__ makes it easier to attach semantic actions. You just
664inline your lambda expressions:
665
666 g[phoenix-lambda-expression]
667
668__karma__ provides some __boost_phoenix__ placeholders to access important
669information from the `Attrib` and `Context` that are otherwise fiddly to extract.
670
671[variablelist Spirit.Karma specific Phoenix placeholders
672 [[`_1, _2, ... , _N`] [Nth attribute of `g`]]
673 [[`_val`] [The enclosing rule's synthesized attribute.]]
674 [[`_r1, _r2, ... , _rN`] [The enclosing rule's Nth inherited attribute.]]
675 [[`_a, _b, ... , _j`] [The enclosing rule's local variables (`_a` refers to the first).]]
676 [[`_pass`] [Assign `false` to `_pass` to force a generator failure.]]
677]
678
679[important All placeholders mentioned above are defined in the namespace
680 `boost::spirit` and, for your convenience, are available in the
681 namespace `boost::spirit::karma` as well.]
682
683For more information see __karma_actions__.
684
685[endsect]
686
687
Ceph