]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Joel de Guzman | |
3 | Copyright (C) 2001-2011 Hartmut Kaiser | |
4 | ||
5 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
6 | file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
7 | ===============================================================================/] | |
8 | ||
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] |