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.and_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__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 __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 688