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 a sort of a "cheat-sheet" on the most commonly used X3 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 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_raw__`[a]`] [__boost_iterator_range__`<I>`] [Presents the transduction of `a` as an iterator range]] 201 202 [[__x3_expectd__`[a]`] [`A`] [Throw an exception if parsing `a` fails]] 203 204 [[[x3_repeat `repeat[a]`]] [`vector<A>`] [Repeat `a` zero or more times]] 205 [[[x3_repeat `repeat(N)[a]`]] [`vector<A>`] [Repeat `a` `N` times]] 206 [[[x3_repeat `repeat(N, M)[a]`]] [`vector<A>`] [Repeat `a` `N` to `M` times]] 207 [[[x3_repeat `repeat(N, inf)[a]`]] [`vector<A>`] [Repeat `a` `N` or more times]] 208 209 [[__x3_skip__`[a]`] [`A`] [Re-establish the skipper that got inhibited by lexeme or no_skip.]] 210 [[__x3_skip__`(p)[a]`] [`A`] [Use `p` as a skipper for parsing `a`]] 211] 212 213[endsect] 214[section:operator Parser Operators] 215 216[table 217 [[Expression] [Attribute] [Description]] 218 [[__x3_not_predicate__] [`Unused`] [Not predicate. If the predicate `a` matches, 219 fail. Otherwise, return a zero length match.]] 220 [[__x3_and_predicate__] [`Unused`] [And predicate. If the predicate `a` matches, 221 return a zero length match. Otherwise, fail.]] 222 [[__x3_optional__] [`optional<A>`] [Optional. Parse `a` zero or one time]] 223 [[__x3_kleene__] [`vector<A>`] [Kleene. Parse `a` zero or more times]] 224 [[__x3_plus__] [`vector<A>`] [Plus. Parse `a` one or more times]] 225 [[__x3_alternative__] [`variant<A, B>`] [Alternative. Parse `a` or `b`]] 226 [[__x3_sequence__] [`tuple<A, B>`] [Sequence. Parse `a` followed by `b`]] 227 [[__x3_expect__] [`tuple<A, B>`] [Expect. Parse `a` followed by `b`. `b` is 228 expected to match when `a` matches, otherwise, 229 an `expectation_failure` is thrown.]] 230 [[__x3_difference__] [`A`] [Difference. Parse `a` but not `b`]] 231 [[__x3_list__] [`vector<A>`] [List. Parse `a` delimited `b` one or more times]] 232] 233 234[endsect] 235[section:action Parser Semantic Actions] 236 237[table 238 [[Expression] [Attribute] [Description]] 239 [[`p[fa]`] [Attribute of `p`] [Call semantic action, `fa` if p succeeds.]] 240] 241 242[endsect] 243[section Compound Attribute Rules] 244 245[heading Notation] 246 247The notation we will use will be of the form: 248 249 a: A, b: B, ... --> composite-expression: composite-attribute 250 251`a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's 252attribute types. `composite-expression` is the expression involving the 253operands and `composite-attribute` is the resulting attribute type of 254the composite expression. 255 256For instance: 257 258 a: A, b: B --> (a >> b): tuple<A, B> 259 260reads as: given, `a` and `b` are parsers, and `A` is the type of the 261attribute of `a`, and `B` is the type of the attribute of `b`, then the 262type of the attribute of `a >> b` will be `tuple<A, B>`. 263 264[important In the attribute tables, we will use `vector<A>` and 265`tuple<A, B...>` as placeholders only. The notation of `vector<A>` 266stands for ['any __stl__ container] holding elements of type `A` and the 267notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding 268`A`, `B`, ... etc. elements. Finally, `Unused` stands for 269__unused_type__. ] 270 271[heading Compound Parser Attribute Types] 272 273[table 274 [[Expression] [Attribute]] 275 276 [[__x3_sequence__ (`a >> b`)] 277[``a: A, b: B --> (a >> b): tuple<A, B> 278a: A, b: Unused --> (a >> b): A 279a: Unused, b: B --> (a >> b): B 280a: Unused, b: Unused --> (a >> b): Unused 281 282a: A, b: A --> (a >> b): vector<A> 283a: vector<A>, b: A --> (a >> b): vector<A> 284a: A, b: vector<A> --> (a >> b): vector<A> 285a: vector<A>, b: vector<A> --> (a >> b): vector<A>``]] 286 287 [[__x3_expect__ (`a > b`)] 288[``a: A, b: B --> (a > b): tuple<A, B> 289a: A, b: Unused --> (a > b): A 290a: Unused, b: B --> (a > b): B 291a: Unused, b: Unused --> (a > b): Unused 292 293a: A, b: A --> (a > b): vector<A> 294a: vector<A>, b: A --> (a > b): vector<A> 295a: A, b: vector<A> --> (a > b): vector<A> 296a: vector<A>, b: vector<A> --> (a > b): vector<A>``]] 297 298 [[__x3_alternative__ (`a | b`)] 299[``a: A, b: B --> (a | b): variant<A, B> 300a: A, b: Unused --> (a | b): optional<A> 301a: A, b: B, c: Unused --> (a | b | c): optional<variant<A, B> > 302a: Unused, b: B --> (a | b): optional<B> 303a: Unused, b: Unused --> (a | b): Unused 304a: A, b: A --> (a | b): A``]] 305 306 [[__x3_difference__ (`a - b`)] 307[``a: A, b: B --> (a - b): A 308a: Unused, b: B --> (a - b): Unused``]] 309 310 [[__x3_kleene__ (`*a`)] 311[``a: A --> *a: vector<A> 312a: Unused --> *a: Unused``]] 313 [[__x3_plus__ (`+a`)] 314[``a: A --> +a: vector<A> 315a: Unused --> +a: Unused``]] 316 317 [[__x3_list__ (`a % b`)] 318[``a: A, b: B --> (a % b): vector<A> 319a: Unused, b: B --> (a % b): Unused``]] 320 321 [[[/ $$$ FIXME $$$ link spirit.x3.reference.directive.repeat] `repeat(...,...)[a]`] 322[``a: A --> repeat(...,...)[a]: vector<A> 323a: Unused --> repeat(...,...)[a]: Unused``]] 324 325 [[__x3_optional__ (`-a`)] 326[``a: A --> -a: optional<A> 327a: Unused --> -a: Unused``]] 328 329 [[`&a`] [`a: A --> &a: Unused`]] 330 [[`!b`] [`a: A --> !a: Unused`]] 331 332] 333 334[endsect] 335 336[section:non_terminals Nonterminals] 337 338[variablelist Notation 339 [[`Attr`] [Synthesized attribute. The rule return type.]] 340 [[`ID`] [The rule ID]] 341 [[`r, r2`] [Rules]] 342 [[`r_def, r2_def`] [A rule definition. By convention a rule named `r` should 343 have corresponding rule definition named `r_def`]] 344 [[`p`] [A parser expression]] 345] 346 347[table 348 [[Expression] [Description]] 349 [[`rule<ID, Attr> const r = name;`] [Rule declaration. `ID` is required. 350 `Attr` is optional and defaults to __unused_type__. 351 `name` is an optional string that gives the rule 352 its name, useful for debugging and error handling.]] 353 [[`r.name()`] [Getting the name of a rule]] 354 [[`auto const r_def = p;`] [Rule definition]] 355 [[`BOOST_SPIRIT_DEFINE(r, r2, ...)`] [Links one or more rules (`r, r2, ...`) with 356 their definitions (`r_def, r2_def, ...`)]] 357] 358 359[endsect] 360[section:semantic_actions Parser Semantic Actions] 361 362Has the form: 363 364 p[f] 365 366where `f` is a function with the signatures: 367 368 void f(Context&); 369 370[/ $$$ TODO $$$ Fix this link: For more detailed information about semantic actions see:] 371 372[endsect] 373