libs/spirit/doc/qi/quick_reference.qbk

   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
   9 This quick reference section is provided for convenience. You can use
  10 this section as a sort of a "cheat-sheet" on the most commonly used Qi
  11 components. It is not intended to be complete, but should give you an
  12 easy way to recall a particular component without having to dig up on
  13 pages and pages of reference documentation.
  14
  15 [section Common Notation]
  16
  17 [variablelist Notation
  18     [[`P`]              [Parser type]]
  19     [[`p, a, b, c`]     [Parser objects]]
  20     [[`A, B, C`]        [Attribute types of parsers `a`, `b` and `c`]]
  21     [[`I`]              [The iterator type used for parsing]]
  22     [[`Unused`]         [An `unused_type`]]
  23     [[`Context`]        [The enclosing rule's `Context` type]]
  24     [[`attrib`]         [An attribute value]]
  25     [[`Attrib`]         [An attribute type]]
  26     [[`b`]              [A boolean expression]]
  27     [[`fp`]             [A (lazy parser) function with signature `P(Unused, Context)`]]
  28     [[`fa`]             [A (semantic action) function with signature `void(Attrib, Context, bool&)`.
  29                         The third parameter is a boolean flag that can be set to false to
  30                         force the parse to fail. Both `Context` and the boolean flag are
  31                         optional.]]
  32     [[`first`]          [An iterator pointing to the start of input]]
  33     [[`last`]           [An iterator pointing to the end of input]]
  34     [[`Ch`]             [Character-class specific character type (See __char_class_types__)]]
  35     [[`ch`]             [Character-class specific character (See __char_class_types__)]]
  36     [[`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     [[`tuple<>`]        [Used as a placeholder for a fusion sequence]]
  41     [[`vector<>`]       [Used as a placeholder for an STL container]]
  42     [[`variant<>`]      [Used as a placeholder for a boost::variant]]
  43     [[`optional<>`]     [Used as a placeholder for a boost::optional]]
  44 ]
  45
  46 [endsect]
  47 [section:qi_parsers Qi Parsers]
  48
  49 [section:char Character Parsers]
  50
  51 [table
  52     [[Expression]                [Attribute]       [Description]]
  53     [[[qi_char `ch`]]            [`Unused`]        [Matches `ch`]]
  54     [[[qi_char `lit(ch)`]]       [`Unused`]        [Matches `ch`]]
  55     [[[qi_char `char_`]]         [`Ch`]            [Matches any character]]
  56     [[[qi_char `char_(ch)`]]     [`Ch`]            [Matches `ch`]]
  57     [[[qi_char `char_("c")`]]    [`Ch`]            [Matches a single char string literal, `c`]]
  58     [[[qi_char `char_(ch, ch2)`]][`Ch`]            [Matches a range of chars from `ch` to `ch2` (inclusive)]]
  59     [[[qi_char `char_(charset)`]][`Ch`]            [Matches a character set `charset`]]
  60
  61     [[[qi_char_class `alnum`]]   [`Ch`]            [Matches a character based on the equivalent of
  62                                    `std::isalnum` in the current character set]]
  63     [[[qi_char_class `alpha`]]   [`Ch`]            [Matches a character based on the equivalent of
  64                                    `std::isalpha` in the current character set]]
  65     [[[qi_char_class `blank`]]   [`Ch`]            [Matches a character based on the equivalent of
  66                                    `std::isblank` in the current character set]]
  67     [[[qi_char_class `cntrl`]]   [`Ch`]            [Matches a character based on the equivalent of
  68                                    `std::iscntrl` in the current character set]]
  69     [[[qi_char_class `digit`]]   [`Ch`]            [Matches a character based on the equivalent of
  70                                    `std::isdigit` in the current character set]]
  71     [[[qi_char_class `graph`]]   [`Ch`]            [Matches a character based on the equivalent of
  72                                    `std::isgraph` in the current character set]]
  73     [[[qi_char_class `print`]]   [`Ch`]            [Matches a character based on the equivalent of
  74                                    `std::isprint` in the current character set]]
  75     [[[qi_char_class `punct`]]   [`Ch`]            [Matches a character based on the equivalent of
  76                                    `std::ispunct` in the current character set]]
  77     [[[qi_char_class `space`]]   [`Ch`]            [Matches a character based on the equivalent of
  78                                    `std::isspace` in the current character set]]
  79     [[[qi_char_class `xdigit`]]  [`Ch`]            [Matches a character based on the equivalent of
  80                                    `std::isxdigit` in the current character set]]
  81     [[[qi_char_class `lower`]]   [`Ch`]            [Matches a character based on the equivalent of
  82                                    `std::islower` in the current character set]]
  83     [[[qi_char_class `upper`]]   [`Ch`]            [Matches a character based on the equivalent of
  84                                    `std::isupper` in the current character set]]
  85 ]
  86
  87 [endsect]
  88 [section:numeric Numeric Parsers]
  89
  90 [table
  91     [[Expression]                 [Attribute]           [Description]]
  92     [[[qi_real_number `float_`]]  [`float`]             [Parse a floating point number into a `float`]]
  93     [[[qi_real_number `float_(num)`]]  [`float`]        [Parse a floating point number into a `float`,
  94                                                             a number is matched only if it's `num`]]
  95     [[[qi_real_number `double_`]] [`double`]            [Parse a floating point number into a `double`]]
  96     [[[qi_real_number `double_(num)`]] [`double`]            [Parse a floating point number into a `double`,
  97                                                             a number is matched only if it's `num`]]
  98     [[[qi_real_number `long_double`]] [`long double`]   [Parse a floating point number into a `long double`]]
  99     [[[qi_real_number `long_double(num)`]] [`long double`]   [Parse a floating point number into a `long double`,
 100                                                             a number is matched only if it's `num`]]
 101
 102     [[[qi_unsigned_int `bin`]]     [`unsigned`]                [Parse a binary integer into an `unsigned`]]
 103     [[[qi_unsigned_int `oct`]]     [`unsigned`]                [Parse an octal integer into an `unsigned`]]
 104     [[[qi_unsigned_int `hex`]]     [`unsigned`]                [Parse a hexadecimal integer into an `unsigned`]]
 105     [[[qi_unsigned_int `ushort_`]] [`unsigned short`]          [Parse an unsigned short integer]]
 106     [[[qi_unsigned_int `ushort_(num)`]] [`unsigned short`]     [Parse an unsigned short integer,
 107                                                             a number is matched only if it's `num`]]
 108     [[[qi_unsigned_int `ulong_`]]  [`unsigned long`]           [Parse an unsigned long integer]]
 109     [[[qi_unsigned_int `ulong_(num)`]]  [`unsigned long`]      [Parse an unsigned long integer,
 110                                                             a number is matched only if it's `num`]]
 111     [[[qi_unsigned_int `uint_`]]   [`unsigned int`]            [Parse an unsigned int]]
 112     [[[qi_unsigned_int `uint_(num)`]]   [`unsigned int`]       [Parse an unsigned int,
 113                                                             a number is matched only if it's `num`]]
 114     [[[qi_unsigned_int `ulong_long`]] [`unsigned long long`]   [Parse an unsigned long long]]
 115     [[[qi_unsigned_int `ulong_long(num)`]] [`unsigned long long`]   [Parse an unsigned long long,
 116                                                             a number is matched only if it's `num`]]
 117     [[[qi_signed_int `short_`]]    [`short`]                   [Parse a short integer]]
 118     [[[qi_signed_int `short_(num)`]]    [`short`]              [Parse a short integer,
 119                                                             a number is matched only if it's `num`]]
 120     [[[qi_signed_int `long_`]]     [`long`]                    [Parse a long integer]]
 121     [[[qi_signed_int `long_(num)`]]     [`long`]               [Parse a long integer,
 122                                                             a number is matched only if it's `num`]]
 123     [[[qi_signed_int `int_`]]      [`int`]                     [Parse an int]]
 124     [[[qi_signed_int `int_(num)`]]      [`int`]                [Parse an int,
 125                                                             a number is matched only if it's `num`]]
 126     [[[qi_signed_int `long_long`]] [`long long`]               [Parse a long long]]
 127     [[[qi_signed_int `long_long(num)`]] [`long long`]          [Parse a long long,
 128                                                             a number is matched only if it's `num`]]
 129 ]
 130
 131 [endsect]
 132 [section:string String Parsers]
 133
 134 [table
 135     [[Expression]           [Attribute]                 [Description]]
 136     [[[qi_lit_string `str`]]          [`Unused`]    [Matches `str`]]
 137     [[[qi_lit_string `lit(str)`]]     [`Unused`]    [Matches `str`]]
 138     [[[qi_lit_string `string(str)`]]  [`Str`]       [Matches `str`]]
 139
 140     [[__qi_symbols__]       [N/A]                       [Declare a symbol table, `sym`. `Ch` is the
 141                                                         underlying char type of the symbol table keys.
 142                                                         `T` is the data type associated with each key.]]
 143     [[
 144 ``
 145     sym.add
 146         (str1, val1)
 147         (str2, val2)
 148         /*...more...*/
 149     ;
 150 ``
 151     ]
 152     [N/A]                                               [Add symbols into a symbol table, `sym`.
 153                                                         val1 and val2 are optional data of type `T`,
 154                                                         the data type associated with each key.]]
 155     [[`sym`]                [`T`]                       [Matches entries in the symbol table, `sym`. If
 156                                                         successful, returns the data associated with
 157                                                         the key]]
 158 ]
 159
 160 [endsect]
 161 [section:auxiliary Auxiliary Parsers]
 162
 163 [table
 164     [[Expression]           [Attribute]                 [Description]]
 165     [[__qi_eol__]           [`Unused`]                  [Matches the end of line (`\r` or `\n` or `\r\n`)]]
 166     [[__qi_eoi__]           [`Unused`]                  [Matches the end of input (first == last)]]
 167     [[__qi_eps__]           [`Unused`]                  [Match an empty string]]
 168     [[__qi_eps__`(b)`]      [`Unused`]                  [If `b` is true, match an empty string]]
 169     [[__qi_lazy__`(fp)`]    [Attribute of `P` where `P`
 170                             is the return type of `fp`] [Invoke `fp` at parse time, returning a parser
 171                                                         `p` which is then called to parse.]]
 172     [[`fp`]                 [see `lazy(fp)` above]      [Equivalent to `lazy(fp)`]]
 173     [[__qi_attr__]          [`Attrib`]                  [Doesn't consume/parse any input, but exposes the
 174                                                          argument `attrib` as its attribute.]]
 175 ]
 176
 177 [endsect]
 178 [section:binary Binary Parsers]
 179
 180 [table
 181     [[Expression]                   [Attribute]                 [Description]]
 182     [[[qi_native_binary `byte_`]]   [8 bits native endian]      [Matches an 8 bit binary in native endian representation]]
 183     [[[qi_native_binary `word`]]    [16 bits native endian]     [Matches a 16 bit binary in native endian representation]]
 184     [[[qi_big_binary `big_word`]]   [16 bits big endian]        [Matches a 16 bit binary in big endian representation]]
 185     [[[qi_little_binary `little_word`]]  [16 bits little endian][Matches a 16 bit binary in little endian representation]]
 186     [[[qi_native_binary `dword`]]   [32 bits native endian]     [Matches a 32 bit binary in native endian representation]]
 187     [[[qi_big_binary `big_dword`]]  [32 bits big endian]        [Matches a 32 bit binary in big endian representation]]
 188     [[[qi_little_binary `little_dword`]] [32 bits little endian][Matches a 32 bit binary in little endian representation]]
 189     [[[qi_native_binary `qword`]]   [64 bits native endian]     [Matches a 64 bit binary in native endian representation]]
 190     [[[qi_big_binary `big_qword`]]  [64 bits big endian]        [Matches a 64 bit binary in big endian representation]]
 191     [[[qi_little_binary `little_qword`]] [64 bits little endian][Matches a 64 bit binary in little endian representation]]
 192 ]
 193
 194 [endsect]
 195
 196 [section:auto Auto Parsers]
 197
 198 See here for more information about [qi_auto Auto Parsers].
 199
 200 [table
 201     [[Expression]           [Attribute]     [Description]]
 202     [[[qi_auto `auto_`]]    [`hold_any`]    [Parse input using a parser
 203                                              created from the supplied attribute type
 204                                              using the __create_parser__ API function.]]
 205 ]
 206
 207 [endsect]
 208
 209 [section:directive Parser Directives]
 210
 211 [table
 212     [[Expression]                   [Attribute]                     [Description]]
 213     [[__qi_lexeme__`[a]`]           [`A`]                           [Disable skip parsing for `a`, does pre-skipping]]
 214     [[[qi_no_skip `no_skip[a]`]]    [`A`]                           [Disable skip parsing for `a`, no pre-skipping]]
 215     [[__qi_no_case__`[a]`]          [`A`]                           [Inhibits case-sensitivity for `a`]]
 216     [[__qi_omit__`[a]`]             [`Unused`]                      [Ignores the attribute type of `a`]]
 217     [[__qi_matches__`[a]`]          [`bool`]                        [Return if the embedded parser `a` matched its input]]
 218
 219     [[__qi_as__`()[a]`]             [`A`]                           [Force atomic assignment for arbitrary attribute types]]
 220     [[__qi_as_string__`[a]`]        [`A`]                           [Force atomic assignment for string attributes]]
 221     [[__qi_as_wstring__`[a]`]       [`A`]                           [Force atomic assignment for wide character string attributes]]
 222
 223     [[__qi_raw__`[a]`]              [__boost_iterator_range__`<I>`] [Presents the transduction of `a` as an iterator range]]
 224
 225     [[[qi_repeat `repeat[a]`]]      [`vector<A>`]                   [Repeat `a` zero or more times]]
 226     [[[qi_repeat `repeat(N)[a]`]]         [`vector<A>`]             [Repeat `a` `N` times]]
 227     [[[qi_repeat `repeat(N, M)[a]`]]      [`vector<A>`]             [Repeat `a` `N` to `M` times]]
 228     [[[qi_repeat `repeat(N, inf)[a]`]]    [`vector<A>`]             [Repeat `a` `N` or more times]]
 229
 230     [[__qi_skip__`[a]`]             [`A`]                           [Re-establish the skipper that got inhibited by lexeme or no_skip.]]
 231     [[__qi_skip__`(p)[a]`]          [`A`]                           [Use `p` as a skipper for parsing `a`]]
 232 ]
 233
 234 [endsect]
 235 [section:operator Parser Operators]
 236
 237 [table
 238     [[Expression]           [Attribute]                 [Description]]
 239     [[[link spirit.qi.reference.operator.not_predicate `!a`]]
 240                             [`Unused`]                  [Not predicate. If the predicate `a` matches,
 241                                                         fail. Otherwise, return a zero length match.]]
 242     [[[link spirit.qi.reference.operator.and_predicate `&a`]]
 243                             [`Unused`]                  [And predicate. If the predicate `a` matches,
 244                                                         return a zero length match. Otherwise, fail.]]
 245     [[[link spirit.qi.reference.operator.optional `-a`]]
 246                             [`optional<A>`]             [Optional. Parse `a` zero or one time]]
 247     [[[link spirit.qi.reference.operator.kleene `*a`]]
 248                             [`vector<A>`]               [Kleene. Parse `a` zero or more times]]
 249     [[[link spirit.qi.reference.operator.plus `+a`]]
 250                             [`vector<A>`]               [Plus. Parse `a` one or more times]]
 251     [[[link spirit.qi.reference.operator.alternative `a | b`]]
 252                             [`variant<A, B>`]           [Alternative. Parse `a` or `b`]]
 253     [[[link spirit.qi.reference.operator.sequence `a >> b`]]
 254                             [`tuple<A, B>`]             [Sequence. Parse `a` followed by `b`]]
 255     [[[link spirit.qi.reference.operator.expect `a > b`]]
 256                             [`tuple<A, B>`]             [Expect. Parse `a` followed by `b`. `b` is
 257                                                         expected to match when `a` matches, otherwise,
 258                                                         an `expectation_failure` is thrown.]]
 259     [[[link spirit.qi.reference.operator.difference `a - b`]]
 260                             [`A`]                       [Difference. Parse `a` but not `b`]]
 261     [[[link spirit.qi.reference.operator.sequential_or `a || b`]]
 262                             [`tuple<`
 263                                 `optional<A>,`
 264                                 `optional<B> >`
 265                             ]                           [Sequential Or. Parse `a` or `b` or `a` followed by `b`]]
 266     [[[link spirit.qi.reference.operator.list `a % b`]]
 267                             [`vector<A>`]               [List. Parse `a` delimited `b` one or more times]]
 268     [[[link spirit.qi.reference.operator.permutation `a ^ b`]]
 269                             [`tuple<`
 270                                 `optional<A>,`
 271                                 `optional<B> >`
 272                             ]                           [Permutation. Parse `a` or `b` or `a` followed by `b` or `b` followed by `a`.]]
 273 ]
 274
 275 [endsect]
 276 [section:action Parser Semantic Actions]
 277
 278 [table
 279     [[Expression]           [Attribute]                 [Description]]
 280     [[`p[fa]`]              [Attribute of `p`]          [Call semantic action, `fa` if p succeeds.]]
 281 ]
 282
 283 [endsect]
 284 [endsect]
 285 [section Compound Attribute Rules]
 286
 287 [heading Notation]
 288
 289 The notation we will use will be of the form:
 290
 291     a: A, b: B, ... --> composite-expression: composite-attribute
 292
 293 `a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's
 294 attribute types. `composite-expression` is the expression involving the
 295 operands and `composite-attribute` is the resulting attribute type of
 296 the composite expression.
 297
 298 For instance:
 299
 300     a: A, b: B --> (a >> b): tuple<A, B>
 301
 302 reads as: given, `a` and `b` are parsers, and `A` is the type of the
 303 attribute of `a`, and `B` is the type of the attribute of `b`, then the
 304 type of the attribute of `a >> b` will be `tuple<A, B>`.
 305
 306 [important In the attribute tables, we will use `vector<A>` and
 307 `tuple<A, B...>` as placeholders only. The notation of `vector<A>`
 308 stands for ['any __stl__ container] holding elements of type `A` and the
 309 notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding
 310 `A`, `B`, ... etc. elements. Finally, `Unused` stands for
 311 __unused_type__. ]
 312
 313 [heading Compound Parser Attribute Types]
 314
 315 [table
 316     [[Expression]           [Attribute]]
 317
 318     [[__qi_sequence__ (`a >> b`)]
 319 [``a: A, b: B --> (a >> b): tuple<A, B>
 320 a: A, b: Unused --> (a >> b): A
 321 a: Unused, b: B --> (a >> b): B
 322 a: Unused, b: Unused --> (a >> b): Unused
 323
 324 a: A, b: A --> (a >> b): vector<A>
 325 a: vector<A>, b: A --> (a >> b): vector<A>
 326 a: A, b: vector<A> --> (a >> b): vector<A>
 327 a: vector<A>, b: vector<A> --> (a >> b): vector<A>``]]
 328
 329     [[__qi_expect__ (`a > b`)]
 330 [``a: A, b: B --> (a > b): tuple<A, B>
 331 a: A, b: Unused --> (a > b): A
 332 a: Unused, b: B --> (a > b): B
 333 a: Unused, b: Unused --> (a > b): Unused
 334
 335 a: A, b: A --> (a > b): vector<A>
 336 a: vector<A>, b: A --> (a > b): vector<A>
 337 a: A, b: vector<A> --> (a > b): vector<A>
 338 a: vector<A>, b: vector<A> --> (a > b): vector<A>``]]
 339
 340     [[__qi_alternative__ (`a | b`)]
 341 [``a: A, b: B --> (a | b): variant<A, B>
 342 a: A, b: Unused --> (a | b): optional<A>
 343 a: A, b: B, c: Unused --> (a | b | c): optional<variant<A, B> >
 344 a: Unused, b: B --> (a | b): optional<B>
 345 a: Unused, b: Unused --> (a | b): Unused
 346 a: A, b: A --> (a | b): A``]]
 347
 348     [[__qi_difference__ (`a - b`)]
 349 [``a: A, b: B --> (a - b): A
 350 a: Unused, b: B --> (a - b): Unused``]]
 351
 352     [[__qi_kleene__ (`*a`)]
 353 [``a: A --> *a: vector<A>
 354 a: Unused --> *a: Unused``]]
 355     [[__qi_plus__ (`+a`)]
 356 [``a: A --> +a: vector<A>
 357 a: Unused --> +a: Unused``]]
 358
 359     [[__qi_list__ (`a % b`)]
 360 [``a: A, b: B --> (a % b): vector<A>
 361 a: Unused, b: B --> (a % b): Unused``]]
 362
 363     [[[link spirit.qi.reference.directive.repeat `repeat(...,...)[a]`]]
 364 [``a: A --> repeat(...,...)[a]: vector<A>
 365 a: Unused --> repeat(...,...)[a]: Unused``]]
 366
 367     [[__qi_sequential_or__ (`a || b`)]
 368 [``a: A, b: B --> (a || b): tuple<optional<A>, optional<B> >
 369 a: A, b: Unused --> (a || b): optional<A>
 370 a: Unused, b: B --> (a || b): optional<B>
 371 a: Unused, b: Unused --> (a || b): Unused
 372
 373 a: A, b: A --> (a || b): vector<optional<A> >``]]
 374
 375     [[__qi_optional__ (`-a`)]
 376 [``a: A --> -a: optional<A>
 377 a: Unused --> -a: Unused``]]
 378
 379     [[`&a`]  [`a: A --> &a: Unused`]]
 380     [[`!b`]  [`a: A --> !a: Unused`]]
 381
 382     [[__qi_permutation__ (`a ^ b`)]
 383 [``a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> >
 384 a: A, b: Unused --> (a ^ b): optional<A>
 385 a: Unused, b: B --> (a ^ b): optional<B>
 386 a: Unused, b: Unused --> (a ^ b): Unused``]]
 387 ]
 388
 389 [endsect]
 390
 391 [section:non_terminals Nonterminals]
 392
 393 [variablelist Notation
 394     [[`RT`]                     [Synthesized attribute. The rule or grammar's return type.]]
 395     [[`Arg1`, `Arg2`, `ArgN`]   [Inherited attributes. Zero or more arguments.]]
 396     [[`L1`, `L2`, `LN`]         [Zero or more local variables.]]
 397     [[`r, r2`]                  [Rules]]
 398     [[`g`]                      [A grammar]]
 399     [[`p`]                      [A parser expression]]
 400     [[`my_grammar`]             [A user defined grammar]]
 401 ]
 402
 403 [variablelist Terminology
 404     [[Signature]                [`RT(Arg1, Arg2 ... ,ArgN)`. The signature specifies
 405                                 the synthesized (return value) and inherited (arguments)
 406                                 attributes.]]
 407     [[Locals]                   [`locals<L1, L2 ..., LN>`. The local variables.]]
 408     [[Skipper]                  [The skip-parser type]]
 409 ]
 410
 411 [variablelist Template Arguments
 412     [[`Iterator`]               [The iterator type you will use for parsing.]]
 413     [[`A1`, `A2`, `A3`]         [Can be one of 1) Signature 2) Locals 3) Skipper.]]
 414 ]
 415
 416 [table
 417     [[Expression]                               [Description]]
 418     [[`rule<Iterator, A1, A2, A3> r(name);`]    [Rule declaration. `Iterator` is required.
 419                                                 `A1, A2, A3` are optional and can be specified in any order.
 420                                                 `name` is an optional string that gives the rule
 421                                                 its name, useful for debugging and error handling.]]
 422     [[`rule<Iterator, A1, A2, A3> r(r2);`]      [Copy construct rule `r` from rule `r2`.]]
 423     [[`r = r2;`]                                [Assign rule `r2` to `r`.]]
 424     [[`r.alias()`]                              [return an alias of `r`. The alias is a parser that
 425                                                 holds a reference to `r`. Reference semantics.]]
 426     [[`r.copy()`]                               [Get a copy of `r`.]]
 427     [[`r.name(name)`]                           [Naming a rule]]
 428     [[`r.name()`]                               [Getting the name of a rule]]
 429     [[debug(r)]                                 [Debug rule `r`]]
 430     [[`r = p;`]                                 [Rule definition]]
 431     [[`r %= p;`]                                [Auto-rule definition. The attribute of `p` should be
 432                                                 compatible with the synthesized attribute of `r`. When `p`
 433                                                 is successful, its attribute is automatically propagated
 434                                                 to `r`'s synthesized attribute.]]
 435
 436     [[
 437 ``
 438     template <typename Iterator>
 439     struct my_grammar : grammar<Iterator, A1, A2, A3>
 440     {
 441         my_grammar() : my_grammar::base_type(start, name)
 442         {
 443             // Rule definitions
 444             start = /* ... */;
 445         }
 446
 447         rule<Iterator, A1, A2, A3> start;
 448         // more rule declarations...
 449     };
 450 ``
 451     ]                                           [Grammar definition. `name` is an optional string that gives the
 452                                                 grammar its name, useful for debugging and error handling.]]
 453     [[`g.name(name)`]                           [Naming a grammar]]
 454     [[`g.name()`]                               [Getting the name of a grammar]]
 455 ]
 456
 457 [endsect]
 458 [section:semantic_actions Parser Semantic Actions]
 459
 460 Has the form:
 461
 462     p[f]
 463
 464 where `f` is a function with the signatures:
 465
 466     void f(Attrib const&);
 467     void f(Attrib const&, Context&);
 468     void f(Attrib const&, Context&, bool&);
 469
 470 You can use __boost_bind__ to bind member functions. For function
 471 objects, the allowed signatures are:
 472
 473     void operator()(Attrib const&, unused_type, unused_type) const;
 474     void operator()(Attrib const&, Context&, unused_type) const;
 475     void operator()(Attrib const&, Context&, bool&) const;
 476
 477 The `unused_type` is used in the signatures above to signify 'don't
 478 care'.
 479
 480 For more detailed information about semantic actions see:
 481 [link spirit.qi.tutorials.semantic_actions here].
 482
 483 [endsect]
 484 [section Phoenix]
 485
 486 __boost_phoenix__ makes it easier to attach semantic actions. You just
 487 inline your lambda expressions:
 488
 489     p[phoenix-lambda-expression]
 490
 491 Spirit.Qi provides some __boost_phoenix__ placeholders to important
 492 information from the `Attrib` and `Context` that are otherwise fiddly to extract.
 493
 494 [variablelist Spirit.Qi specific Phoenix placeholders
 495     [[`_1, _2... , _N`]         [Nth attribute of `p`]]
 496     [[`_val`]                   [The enclosing rule's synthesized attribute.]]
 497     [[`_r1, _r2... , _rN`]      [The enclosing rule's Nth inherited attribute.]]
 498     [[`_a, _b... , _j`]         [The enclosing rule's local variables (`_a` refers to the first).]]
 499     [[`_pass`]                  [Assign `false` to `_pass` to force a parser failure.]]
 500 ]
 501
 502 [important  All placeholders mentioned above are defined in the namespace
 503            `boost::spirit` and, for your convenience, are available in the
 504            namespace `boost::spirit::qi` as well.]
 505
 506 For more detailed information about semantic actions see:
 507 [link spirit.qi.tutorials.semantic_actions here].
 508
 509 [endsect]