ceph/src/boost/libs/spirit/doc/x3/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 X3
  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(Context&)`.]]
  29     [[`first`]          [An iterator pointing to the start of input]]
  30     [[`last`]           [An iterator pointing to the end of input]]
  31     [[`Ch`]             [Character-class specific character type (See __char_class_types__)]]
  32     [[`ch`]             [Character-class specific character (See __char_class_types__)]]
  33     [[`ch2`]            [Character-class specific character (See __char_class_types__)]]
  34     [[`charset`]        [Character-set specifier string (example: "a-z0-9")]]
  35     [[`str`]            [Character-class specific string (See __char_class_types__)]]
  36     [[`Str`]            [Attribute of `str`: `std::basic_string<T>` where `T` is the underlying character type of `str`]]
  37     [[`tuple<>`]        [Used as a placeholder for a fusion sequence]]
  38     [[`vector<>`]       [Used as a placeholder for an STL container]]
  39     [[`variant<>`]      [Used as a placeholder for a boost::variant]]
  40     [[`optional<>`]     [Used as a placeholder for a boost::optional]]
  41 ]
  42
  43 [endsect]
  44 [section:char Character Parsers]
  45
  46 [table
  47     [[Expression]                [Attribute]       [Description]]
  48     [[[x3_char `ch`]]            [`Unused`]        [Matches `ch`]]
  49     [[[x3_char `lit(ch)`]]       [`Unused`]        [Matches `ch`]]
  50     [[[x3_char `char_`]]         [`Ch`]            [Matches any character]]
  51     [[[x3_char `char_(ch)`]]     [`Ch`]            [Matches `ch`]]
  52     [[[x3_char `char_("c")`]]    [`Ch`]            [Matches a single char string literal, `c`]]
  53     [[[x3_char `char_(ch, ch2)`]][`Ch`]            [Matches a range of chars from `ch` to `ch2` (inclusive)]]
  54     [[[x3_char `char_(charset)`]][`Ch`]            [Matches a character set `charset`]]
  55
  56     [[[x3_char_class `alnum`]]   [`Ch`]            [Matches a character based on the equivalent of
  57                                    `std::isalnum` in the current character set]]
  58     [[[x3_char_class `alpha`]]   [`Ch`]            [Matches a character based on the equivalent of
  59                                    `std::isalpha` in the current character set]]
  60     [[[x3_char_class `blank`]]   [`Ch`]            [Matches a character based on the equivalent of
  61                                    `std::isblank` in the current character set]]
  62     [[[x3_char_class `cntrl`]]   [`Ch`]            [Matches a character based on the equivalent of
  63                                    `std::iscntrl` in the current character set]]
  64     [[[x3_char_class `digit`]]   [`Ch`]            [Matches a character based on the equivalent of
  65                                    `std::isdigit` in the current character set]]
  66     [[[x3_char_class `graph`]]   [`Ch`]            [Matches a character based on the equivalent of
  67                                    `std::isgraph` in the current character set]]
  68     [[[x3_char_class `print`]]   [`Ch`]            [Matches a character based on the equivalent of
  69                                    `std::isprint` in the current character set]]
  70     [[[x3_char_class `punct`]]   [`Ch`]            [Matches a character based on the equivalent of
  71                                    `std::ispunct` in the current character set]]
  72     [[[x3_char_class `space`]]   [`Ch`]            [Matches a character based on the equivalent of
  73                                    `std::isspace` in the current character set]]
  74     [[[x3_char_class `xdigit`]]  [`Ch`]            [Matches a character based on the equivalent of
  75                                    `std::isxdigit` in the current character set]]
  76     [[[x3_char_class `lower`]]   [`Ch`]            [Matches a character based on the equivalent of
  77                                    `std::islower` in the current character set]]
  78     [[[x3_char_class `upper`]]   [`Ch`]            [Matches a character based on the equivalent of
  79                                    `std::isupper` in the current character set]]
  80 ]
  81
  82 [endsect]
  83 [section:numeric Numeric Parsers]
  84
  85 [table
  86     [[Expression]                 [Attribute]           [Description]]
  87     [[[x3_real_number `float_`]]  [`float`]             [Parse a floating point number into a `float`]]
  88     [[[x3_real_number `float_(num)`]]  [`float`]        [Parse a floating point number into a `float`,
  89                                                             a number is matched only if it's `num`]]
  90     [[[x3_real_number `double_`]] [`double`]            [Parse a floating point number into a `double`]]
  91     [[[x3_real_number `double_(num)`]] [`double`]            [Parse a floating point number into a `double`,
  92                                                             a number is matched only if it's `num`]]
  93     [[[x3_real_number `long_double`]] [`long double`]   [Parse a floating point number into a `long double`]]
  94     [[[x3_real_number `long_double(num)`]] [`long double`]   [Parse a floating point number into a `long double`,
  95                                                             a number is matched only if it's `num`]]
  96
  97     [[[x3_unsigned_int `bin`]]     [`unsigned`]                [Parse a binary integer into an `unsigned`]]
  98     [[[x3_unsigned_int `oct`]]     [`unsigned`]                [Parse an octal integer into an `unsigned`]]
  99     [[[x3_unsigned_int `hex`]]     [`unsigned`]                [Parse a hexadecimal integer into an `unsigned`]]
 100     [[[x3_unsigned_int `ushort_`]] [`unsigned short`]          [Parse an unsigned short integer]]
 101     [[[x3_unsigned_int `ushort_(num)`]] [`unsigned short`]     [Parse an unsigned short integer,
 102                                                             a number is matched only if it's `num`]]
 103     [[[x3_unsigned_int `ulong_`]]  [`unsigned long`]           [Parse an unsigned long integer]]
 104     [[[x3_unsigned_int `ulong_(num)`]]  [`unsigned long`]      [Parse an unsigned long integer,
 105                                                             a number is matched only if it's `num`]]
 106     [[[x3_unsigned_int `uint_`]]   [`unsigned int`]            [Parse an unsigned int]]
 107     [[[x3_unsigned_int `uint_(num)`]]   [`unsigned int`]       [Parse an unsigned int,
 108                                                             a number is matched only if it's `num`]]
 109     [[[x3_unsigned_int `ulong_long`]] [`unsigned long long`]   [Parse an unsigned long long]]
 110     [[[x3_unsigned_int `ulong_long(num)`]] [`unsigned long long`]   [Parse an unsigned long long,
 111                                                             a number is matched only if it's `num`]]
 112     [[[x3_signed_int `short_`]]    [`short`]                   [Parse a short integer]]
 113     [[[x3_signed_int `short_(num)`]]    [`short`]              [Parse a short integer,
 114                                                             a number is matched only if it's `num`]]
 115     [[[x3_signed_int `long_`]]     [`long`]                    [Parse a long integer]]
 116     [[[x3_signed_int `long_(num)`]]     [`long`]               [Parse a long integer,
 117                                                             a number is matched only if it's `num`]]
 118     [[[x3_signed_int `int_`]]      [`int`]                     [Parse an int]]
 119     [[[x3_signed_int `int_(num)`]]      [`int`]                [Parse an int,
 120                                                             a number is matched only if it's `num`]]
 121     [[[x3_signed_int `long_long`]] [`long long`]               [Parse a long long]]
 122     [[[x3_signed_int `long_long(num)`]] [`long long`]          [Parse a long long,
 123                                                             a number is matched only if it's `num`]]
 124 ]
 125
 126 [endsect]
 127 [section:string String Parsers]
 128
 129 [table
 130     [[Expression]           [Attribute]                 [Description]]
 131     [[[x3_lit_string `str`]]          [`Unused`]    [Matches `str`]]
 132     [[[x3_lit_string `lit(str)`]]     [`Unused`]    [Matches `str`]]
 133     [[[x3_lit_string `string(str)`]]  [`Str`]       [Matches `str`]]
 134
 135     [[__x3_symbols__]       [N/A]                       [Declare a symbol table, `sym`. `T` is the
 136                                                         data type associated with each key.]]
 137     [[
 138 ``
 139     sym.add
 140         (str1, val1)
 141         (str2, val2)
 142         /*...more...*/
 143     ;
 144 ``
 145     ]
 146     [N/A]                                               [Add symbols into a symbol table, `sym`.
 147                                                         val1 and val2 are optional data of type `T`,
 148                                                         the data type associated with each key.]]
 149     [[`sym`]                [`T`]                       [Matches entries in the symbol table, `sym`. If
 150                                                         successful, returns the data associated with
 151                                                         the key]]
 152 ]
 153
 154 [endsect]
 155 [section:auxiliary Auxiliary Parsers]
 156
 157 [table
 158     [[Expression]           [Attribute]                 [Description]]
 159     [[__x3_eol__]           [`Unused`]                  [Matches the end of line (`\r` or `\n` or `\r\n`)]]
 160     [[__x3_eoi__]           [`Unused`]                  [Matches the end of input (first == last)]]
 161     [[__x3_eps__]           [`Unused`]                  [Match an empty string]]
 162     [[__x3_eps__`(b)`]      [`Unused`]                  [If `b` is true, match an empty string]]
 163     [[__x3_lazy__`(fp)`]    [Attribute of `P` where `P`
 164                             is the return type of `fp`] [Invoke `fp` at parse time, returning a parser
 165                                                         `p` which is then called to parse.]]
 166     [[`fp`]                 [see `lazy(fp)` above]      [Equivalent to `lazy(fp)`]]
 167     [[__x3_attr__]          [`Attrib`]                  [Doesn't consume/parse any input, but exposes the
 168                                                          argument `attrib` as its attribute.]]
 169 ]
 170
 171 [endsect]
 172 [section:binary Binary Parsers]
 173
 174 [table
 175     [[Expression]                   [Attribute]                 [Description]]
 176     [[[x3_native_binary `byte_`]]   [8 bits native endian]      [Matches an 8 bit binary in native endian representation]]
 177     [[[x3_native_binary `word`]]    [16 bits native endian]     [Matches a 16 bit binary in native endian representation]]
 178     [[[x3_big_binary `big_word`]]   [16 bits big endian]        [Matches a 16 bit binary in big endian representation]]
 179     [[[x3_little_binary `little_word`]]  [16 bits little endian][Matches a 16 bit binary in little endian representation]]
 180     [[[x3_native_binary `dword`]]   [32 bits native endian]     [Matches a 32 bit binary in native endian representation]]
 181     [[[x3_big_binary `big_dword`]]  [32 bits big endian]        [Matches a 32 bit binary in big endian representation]]
 182     [[[x3_little_binary `little_dword`]] [32 bits little endian][Matches a 32 bit binary in little endian representation]]
 183     [[[x3_native_binary `qword`]]   [64 bits native endian]     [Matches a 64 bit binary in native endian representation]]
 184     [[[x3_big_binary `big_qword`]]  [64 bits big endian]        [Matches a 64 bit binary in big endian representation]]
 185     [[[x3_little_binary `little_qword`]] [64 bits little endian][Matches a 64 bit binary in little endian representation]]
 186 ]
 187
 188 [endsect]
 189
 190 [section:directive Parser Directives]
 191
 192 [table
 193     [[Expression]                   [Attribute]                     [Description]]
 194     [[__x3_lexeme__`[a]`]           [`A`]                           [Disable skip parsing for `a`, does pre-skipping]]
 195     [[[x3_no_skip `no_skip[a]`]]    [`A`]                           [Disable skip parsing for `a`, no pre-skipping]]
 196     [[__x3_no_case__`[a]`]          [`A`]                           [Inhibits case-sensitivity for `a`]]
 197     [[__x3_omit__`[a]`]             [`Unused`]                      [Ignores the attribute type of `a`]]
 198     [[__x3_matches__`[a]`]          [`bool`]                        [Return if the embedded parser `a` matched its input]]
 199
 200     [[__x3_as__`()[a]`]             [`A`]                           [Force atomic assignment for arbitrary attribute types]]
 201     [[__x3_as_string__`[a]`]        [`A`]                           [Force atomic assignment for string attributes]]
 202     [[__x3_as_wstring__`[a]`]       [`A`]                           [Force atomic assignment for wide character string attributes]]
 203
 204     [[__x3_raw__`[a]`]              [__boost_iterator_range__`<I>`] [Presents the transduction of `a` as an iterator range]]
 205
 206     [[[x3_repeat `repeat[a]`]]      [`vector<A>`]                   [Repeat `a` zero or more times]]
 207     [[[x3_repeat `repeat(N)[a]`]]         [`vector<A>`]             [Repeat `a` `N` times]]
 208     [[[x3_repeat `repeat(N, M)[a]`]]      [`vector<A>`]             [Repeat `a` `N` to `M` times]]
 209     [[[x3_repeat `repeat(N, inf)[a]`]]    [`vector<A>`]             [Repeat `a` `N` or more times]]
 210
 211     [[__x3_skip__`[a]`]             [`A`]                           [Re-establish the skipper that got inhibited by lexeme or no_skip.]]
 212     [[__x3_skip__`(p)[a]`]          [`A`]                           [Use `p` as a skipper for parsing `a`]]
 213 ]
 214
 215 [endsect]
 216 [section:operator Parser Operators]
 217
 218 [table
 219     [[Expression]           [Attribute]                 [Description]]
 220     [[__x3_not_predicate__] [`Unused`]                  [Not predicate. If the predicate `a` matches,
 221                                                         fail. Otherwise, return a zero length match.]]
 222     [[__x3_and_predicate__] [`Unused`]                  [And predicate. If the predicate `a` matches,
 223                                                         return a zero length match. Otherwise, fail.]]
 224     [[__x3_optional__]      [`optional<A>`]             [Optional. Parse `a` zero or one time]]
 225     [[__x3_kleene__]        [`vector<A>`]               [Kleene. Parse `a` zero or more times]]
 226     [[__x3_plus__]          [`vector<A>`]               [Plus. Parse `a` one or more times]]
 227     [[__x3_alternative__]   [`variant<A, B>`]           [Alternative. Parse `a` or `b`]]
 228     [[__x3_sequence__]      [`tuple<A, B>`]             [Sequence. Parse `a` followed by `b`]]
 229     [[__x3_expect__]        [`tuple<A, B>`]             [Expect. Parse `a` followed by `b`. `b` is
 230                                                         expected to match when `a` matches, otherwise,
 231                                                         an `expectation_failure` is thrown.]]
 232     [[__x3_difference__]    [`A`]                       [Difference. Parse `a` but not `b`]]
 233     [[__x3_list__]          [`vector<A>`]               [List. Parse `a` delimited `b` one or more times]]
 234 ]
 235
 236 [endsect]
 237 [section:action Parser Semantic Actions]
 238
 239 [table
 240     [[Expression]           [Attribute]                 [Description]]
 241     [[`p[fa]`]              [Attribute of `p`]          [Call semantic action, `fa` if p succeeds.]]
 242 ]
 243
 244 [endsect]
 245 [section Compound Attribute Rules]
 246
 247 [heading Notation]
 248
 249 The notation we will use will be of the form:
 250
 251     a: A, b: B, ... --> composite-expression: composite-attribute
 252
 253 `a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's
 254 attribute types. `composite-expression` is the expression involving the
 255 operands and `composite-attribute` is the resulting attribute type of
 256 the composite expression.
 257
 258 For instance:
 259
 260     a: A, b: B --> (a >> b): tuple<A, B>
 261
 262 reads as: given, `a` and `b` are parsers, and `A` is the type of the
 263 attribute of `a`, and `B` is the type of the attribute of `b`, then the
 264 type of the attribute of `a >> b` will be `tuple<A, B>`.
 265
 266 [important In the attribute tables, we will use `vector<A>` and
 267 `tuple<A, B...>` as placeholders only. The notation of `vector<A>`
 268 stands for ['any __stl__ container] holding elements of type `A` and the
 269 notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding
 270 `A`, `B`, ... etc. elements. Finally, `Unused` stands for
 271 __unused_type__. ]
 272
 273 [heading Compound Parser Attribute Types]
 274
 275 [table
 276     [[Expression]           [Attribute]]
 277
 278     [[__x3_sequence__ (`a >> b`)]
 279 [``a: A, b: B --> (a >> b): tuple<A, B>
 280 a: A, b: Unused --> (a >> b): A
 281 a: Unused, b: B --> (a >> b): B
 282 a: Unused, b: Unused --> (a >> b): Unused
 283
 284 a: A, b: A --> (a >> b): vector<A>
 285 a: vector<A>, b: A --> (a >> b): vector<A>
 286 a: A, b: vector<A> --> (a >> b): vector<A>
 287 a: vector<A>, b: vector<A> --> (a >> b): vector<A>``]]
 288
 289     [[__x3_expect__ (`a > b`)]
 290 [``a: A, b: B --> (a > b): tuple<A, B>
 291 a: A, b: Unused --> (a > b): A
 292 a: Unused, b: B --> (a > b): B
 293 a: Unused, b: Unused --> (a > b): Unused
 294
 295 a: A, b: A --> (a > b): vector<A>
 296 a: vector<A>, b: A --> (a > b): vector<A>
 297 a: A, b: vector<A> --> (a > b): vector<A>
 298 a: vector<A>, b: vector<A> --> (a > b): vector<A>``]]
 299
 300     [[__x3_alternative__ (`a | b`)]
 301 [``a: A, b: B --> (a | b): variant<A, B>
 302 a: A, b: Unused --> (a | b): optional<A>
 303 a: A, b: B, c: Unused --> (a | b | c): optional<variant<A, B> >
 304 a: Unused, b: B --> (a | b): optional<B>
 305 a: Unused, b: Unused --> (a | b): Unused
 306 a: A, b: A --> (a | b): A``]]
 307
 308     [[__x3_difference__ (`a - b`)]
 309 [``a: A, b: B --> (a - b): A
 310 a: Unused, b: B --> (a - b): Unused``]]
 311
 312     [[__x3_kleene__ (`*a`)]
 313 [``a: A --> *a: vector<A>
 314 a: Unused --> *a: Unused``]]
 315     [[__x3_plus__ (`+a`)]
 316 [``a: A --> +a: vector<A>
 317 a: Unused --> +a: Unused``]]
 318
 319     [[__x3_list__ (`a % b`)]
 320 [``a: A, b: B --> (a % b): vector<A>
 321 a: Unused, b: B --> (a % b): Unused``]]
 322
 323     [[[/ $$$ FIXME $$$ link spirit.x3.reference.directive.repeat] `repeat(...,...)[a]`]
 324 [``a: A --> repeat(...,...)[a]: vector<A>
 325 a: Unused --> repeat(...,...)[a]: Unused``]]
 326
 327     [[__x3_optional__ (`-a`)]
 328 [``a: A --> -a: optional<A>
 329 a: Unused --> -a: Unused``]]
 330
 331     [[`&a`]  [`a: A --> &a: Unused`]]
 332     [[`!b`]  [`a: A --> !a: Unused`]]
 333
 334 ]
 335
 336 [endsect]
 337
 338 [section:non_terminals Nonterminals]
 339
 340 [variablelist Notation
 341     [[`Attr`]                   [Synthesized attribute. The rule return type.]]
 342     [[`ID`]                     [The rule ID]]
 343     [[`r, r2`]                  [Rules]]
 344     [[`r_def, r2_def`]          [A rule definition. By convention a rule named `r` should
 345                                 have corresponding rule definition named `r_def`]]
 346     [[`p`]                      [A parser expression]]
 347 ]
 348
 349 [table
 350     [[Expression]                               [Description]]
 351     [[`rule<ID, Attr> const r = name;`]         [Rule declaration. `ID` is required.
 352                                                 `Attr` is optional and defaults to __unused_type__.
 353                                                 `name` is an optional string that gives the rule
 354                                                 its name, useful for debugging and error handling.]]
 355     [[`r.name()`]                               [Getting the name of a rule]]
 356     [[`auto const r_def = p;`]                  [Rule definition]]
 357     [[`BOOST_SPIRIT_DEFINE(r, r2, ...)`]        [Links one or more rules (`r, r2, ...`)  with
 358                                                 their definitions (`r_def, r2_def, ...`)]]
 359 ]
 360
 361 [endsect]
 362 [section:semantic_actions Parser Semantic Actions]
 363
 364 Has the form:
 365
 366     p[f]
 367
 368 where `f` is a function with the signatures:
 369
 370     void f(Context&);
 371
 372 [/ $$$ TODO $$$ Fix this link: For more detailed information about semantic actions see:]
 373
 374 [endsect]