]> git.proxmox.com Git - ceph.git/blame - ceph/src/boost/libs/spirit/classic/doc/quick_start.html
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / spirit / classic / doc / quick_start.html
CommitLineData
7c673cae
FG
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3 <head>
4 <meta content=
5 "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org"
6 name="generator">
7 <title>
8 Quick Start
9 </title>
10 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
11 <link rel="stylesheet" href="theme/style.css" type="text/css">
12 </head>
13 <body>
14 <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2">
15 <tr>
16 <td width="10"></td>
17 <td width="85%">
18 <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Quick
19 Start</b></font>
20 </td>
21 <td width="112">
22 <a href="http://spirit.sf.net"><img src="theme/spirit.gif"
23 width="112" height="48" align="right" border="0"></a>
24 </td>
25 </tr>
26 </table><br>
27 <table border="0">
28 <tr>
29 <td width="10"></td>
30 <td width="30">
31 <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a>
32 </td>
33 <td width="30">
34 <a href="introduction.html"><img src="theme/l_arr.gif" border="0">
35 </a>
36 </td>
37 <td width="30">
38 <a href="basic_concepts.html"><img src="theme/r_arr.gif" border="0">
39 </a>
40 </td>
41 </tr>
42 </table>
43 <h2>
44 <b>Why would you want to use Spirit?</b>
45 </h2>
46 <p>
47 Spirit is designed to be a practical parsing tool. At the very least, the
48 ability to generate a fully-working parser from a formal EBNF
49 specification inlined in C++ significantly reduces development time.
50 While it may be practical to use a full-blown, stand-alone parser such as
51 YACC or ANTLR when we want to develop a computer language such as C or
52 Pascal, it is certainly overkill to bring in the big guns when we wish to
53 write extremely small micro-parsers. At that end of the spectrum,
54 programmers typically approach the job at hand not as a formal parsing
55 task but through ad hoc hacks using primitive tools such as
56 <tt>scanf</tt>. True, there are tools such as regular-expression
57 libraries (such as <a href=
58 "http://www.boost.org/libs/regex/index.html">boost regex</a>) or scanners
59 (such as <a href="http://www.boost.org/libs/tokenizer/index.html">boost
60 tokenizer</a>), but these tools do not scale well when we need to write
61 more elaborate parsers. Attempting to write even a moderately-complex
62 parser using these tools leads to code that is hard to understand and
63 maintain.
64 </p>
65 <p>
66 One prime objective is to make the tool easy to use. When one thinks of a
67 parser generator, the usual reaction is "it must be big and complex with
68 a steep learning curve." Not so. Spirit is designed to be fully scalable.
69 The framework is structured in layers. This permits learning on an
70 as-needed basis, after only learning the minimal core and basic concepts.
71 </p>
72 <p>
73 For development simplicity and ease in deployment, the entire framework
74 consists of only header files, with no libraries to link against or
75 build. Just put the spirit distribution in your include path, compile and
76 run. Code size? -very tight. In the quick start example that we shall
77 present in a short while, the code size is dominated by the instantiation
78 of the <tt>std::vector</tt> and <tt>std::iostream</tt>.
79 </p>
80 <h2>
81 <b>Trivial Example #1</b></h2>
82 <p>Create a parser that will parse
83 a floating-point number.
84 </p>
85 <pre><code><font color="#000000"> </font></code><span class="identifier">real_p</span>
86</pre>
87<p>
88 (You've got to admit, that's trivial!) The above code actually generates
89 a Spirit <tt>real_parser</tt> (a built-in parser) which parses a floating
90 point number. Take note that parsers that are meant to be used directly
91 by the user end with "<tt>_p</tt>" in their names as a Spirit convention.
92 Spirit has many pre-defined parsers and consistent naming conventions
93 help you keep from going insane!
94 </p>
95 <h2>
96 <b>Trivial Example #2</b></h2>
97 <p>
98 Create a parser that will accept a line consisting of two floating-point
99 numbers.
100 </p>
101
102<pre><code><font color="#000000"> </font></code><code><span class=
103"identifier">real_p</span> <span class=
104 "special">&gt;&gt;</span> <span class="identifier">real_p</span></code>
105</pre>
106<p>
107 Here you see the familiar floating-point numeric parser
108 <code><tt>real_p</tt></code> used twice, once for each number. What's
109 that <tt class="operators">&gt;&gt;</tt> operator doing in there? Well,
110 they had to be separated by something, and this was chosen as the
111 "followed by" sequence operator. The above program creates a parser from
112 two simpler parsers, glueing them together with the sequence operator.
113 The result is a parser that is a composition of smaller parsers.
114 Whitespace between numbers can implicitly be consumed depending on how
115 the parser is invoked (see below).
116 </p>
117 <p>
118 Note: when we combine parsers, we end up with a "bigger" parser, But it's
119 still a parser. Parsers can get bigger and bigger, nesting more and more,
120 but whenever you glue two parsers together, you end up with one bigger
121 parser. This is an important concept.
122 </p>
123 <h2>
124 <b>Trivial Example #3</b></h2>
125 <p>
126 Create a parser that will accept an arbitrary number of floating-point
127 numbers. (Arbitrary means anything from zero to infinity)
128 </p>
129
130<pre><code><font color="#000000"> </font></code><code><span class=
131"special">*</span><span class="identifier">real_p</span></code>
132</pre>
133<p>
134 This is like a regular-expression Kleene Star, though the syntax might
135 look a bit odd for a C++ programmer not used to seeing the <tt class=
136 "operators">*</tt> operator overloaded like this. Actually, if you know
137 regular expressions it may look odd too since the star is <b>before</b>
138 the expression it modifies. C'est la vie. Blame it on the fact that we
139 must work with the syntax rules of C++.
140 </p>
141 <p>
142 Any expression that evaluates to a parser may be used with the Kleene
143 Star. Keep in mind, though, that due to C++ operator precedence rules you
144 may need to put the expression in parentheses for complex expressions.
145 The Kleene Star is also known as a Kleene Closure, but we call it the
146 Star in most places.
147 </p>
148 <h3>
149 <b><a name="list_of_numbers"></a> Example #4 [ A Just Slightly Less Trivial Example</b>
150] </h3>
151 <p>
152 This example will create a parser that accepts a comma-delimited list of numbers and put the numbers in a vector.
153</p>
154 <h4><strong> Step 1. Create the parser</strong></h4>
155 <pre><code><font color="#000000"> </font></code><code><span class=
156"identifier">real_p</span> <span class=
157 "special">&gt;&gt;</span> <span class="special">*(</span><span class=
158 "identifier">ch_p</span><span class="special">(</span><span class=
159 "literal">','</span><span class="special">)</span> <span class=
160 "special">&gt;&gt;</span> <span class=
161 "identifier">real_p</span><span class="special">)</span></code>
162</pre>
163 <p>
164 Notice <tt>ch_p(',')</tt>. It is a literal character parser that can
165 recognize the comma <tt>','</tt>. In this case, the Kleene Star is
166 modifying a more complex parser, namely, the one generated by the
167 expression:
168 </p>
169
170 <pre><code><font color="#000000"> </font></code><code><span class=
171 "special">(</span><span class="identifier">ch_p</span><span class=
172 "special">(</span><span class="literal">','</span><span class=
173 "special">)</span> <span class="special">&gt;&gt;</span> <span class=
174 "identifier">real_p</span><span class="special">)</span></code>
175</pre>
176<p>
177 Note that this is a case where the parentheses are necessary. The Kleene
178 star encloses the complete expression above.
179 </p>
180 <h4>
181 <b><strong>Step 2. </strong>Using a Parser (now that it's created)</b></h4>
182 <p>
183 Now that we have created a parser, how do we use it? Like the result of
184 any C++ temporary object, we can either store it in a variable, or call
185 functions directly on it.
186 </p>
187 <p>
188 We'll gloss over some low-level C++ details and just get to the good
189 stuff.
190 </p>
191 <p>
192 If <b><tt>r</tt></b> is a rule (don't worry about what rules exactly are
193 for now. This will be discussed later. Suffice it to say that the rule is
194 a placeholder variable that can hold a parser), then we store the parser
195 as a rule like this:
196 </p>
197
198<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
199 "identifier">r</span> <span class="special">=</span> <span class=
200 "identifier">real_p</span> <span class=
201 "special">&gt;&gt; *(</span><span class=
202 "identifier">ch_p</span><span class="special">(</span><span class=
203 "literal">','</span><span class="special">) &gt;&gt;</span> <span class=
204 "identifier">real_p</span><span class="special">);</span></font></code>
205</pre>
206<p>
207 Not too exciting, just an assignment like any other C++ expression you've
208 used for years. The cool thing about storing a parser in a rule is this:
209 rules are parsers, and now you can refer to it <b>by name</b>. (In this
210 case the name is <tt><b>r</b></tt>). Notice that this is now a full
211 assignment expression, thus we terminate it with a semicolon,
212 "<tt>;</tt>".
213 </p>
214 <p>
215 That's it. We're done with defining the parser. So the next step is now
216 invoking this parser to do its work. There are a couple of ways to do
217 this. For now, we shall use the free <tt>parse</tt> function that takes
218 in a <tt>char const*</tt>. The function accepts three arguments:
219 </p>
220 <blockquote>
221 <p>
222 <img src="theme/bullet.gif" width="12" height="12"> The null-terminated
223 <tt>const char*</tt> input<br>
224 <img src="theme/bullet.gif" width="12" height="12"> The parser
225 object<br>
226 <img src="theme/bullet.gif" width="12" height="12"> Another parser
227 called the <b>skip parser</b>
228 </p>
229 </blockquote>
230 <p>
231 In our example, we wish to skip spaces and tabs. Another parser named
232 <tt>space_p</tt> is included in Spirit's repertoire of predefined
233 parsers. It is a very simple parser that simply recognizes whitespace. We
234 shall use <tt>space_p</tt> as our skip parser. The skip parser is the one
235 responsible for skipping characters in between parser elements such as
236 the <tt>real_p</tt> and the <tt>ch_p</tt>.
237 </p>
238 <p>
239 Ok, so now let's parse!
240 </p>
241
242<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
243"identifier">r</span> <span class="special">=</span> <span class=
244"identifier">real_p</span> <span class=
245 "special">&gt;&gt;</span> <span class="special">*(</span><span class=
246 "identifier">ch_p</span><span class="special">(</span><span class=
247 "literal">','</span><span class="special">)</span> <span class=
248 "special">&gt;&gt;</span> <span class=
249 "identifier">real_p</span><span class="special">);
250</span> <span class="identifier"> parse</span><span class=
251"special">(</span><span class="identifier">str</span><span class=
252"special">,</span> <span class="identifier">r</span><span class=
253"special">,</span> <span class="identifier">space_p</span><span class=
254"special">)</span> <span class=
255"comment">// Not a full statement yet, patience...</span></font></code>
256</pre>
257<p>
258 The parse function returns an object (called <tt>parse_info</tt>) that
259 holds, among other things, the result of the parse. In this example, we
260 need to know:
261 </p>
262 <blockquote>
263 <p>
264 <img src="theme/bullet.gif" width="12" height="12"> Did the parser
265 successfully recognize the input <tt>str</tt>?<br>
266 <img src="theme/bullet.gif" width="12" height="12"> Did the parser
267 <b>fully</b> parse and consume the input up to its end?
268 </p>
269 </blockquote>
270 <p>
271 To get a complete picture of what we have so far, let us also wrap this
272 parser inside a function:
273 </p>
274
275<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
276"keyword">bool
277</span> <span class="identifier"> parse_numbers</span><span class=
278"special">(</span><span class="keyword">char</span> <span class=
279"keyword">const</span><span class="special">*</span> <span class=
280"identifier">str</span><span class="special">)
281 {
282</span> <span class="keyword"> return</span> <span class=
283"identifier">parse</span><span class="special">(</span><span class=
284"identifier">str</span><span class="special">,</span> <span class=
285"identifier">real_p</span> <span class=
286 "special">&gt;&gt;</span> <span class="special">*(</span><span class=
287 "literal">','</span> <span class="special">&gt;&gt;</span> <span class=
288 "identifier">real_p</span><span class="special">),</span> <span class=
289 "identifier">space_p</span><span class="special">).</span><span class=
290 "identifier">full</span><span class="special">;
291 }</span></font></code>
292</pre>
293<p>
294 Note in this case we dropped the named rule and inlined the parser
295 directly in the call to parse. Upon calling parse, the expression
296 evaluates into a temporary, unnamed parser which is passed into the
297 parse() function, used, and then destroyed.
298 </p>
299 <table border="0" width="80%" align="center">
300 <tr>
301 <td class="note_box">
302 <img src="theme/note.gif" width="16" height="16"><b>char and wchar_t
303 operands</b><br>
304 <br>
305 The careful reader may notice that the parser expression has
306 <tt class="quotes">','</tt> instead of <tt>ch_p(',')</tt> as the
307 previous examples did. This is ok due to C++ syntax rules of
308 conversion. There are <tt>&gt;&gt;</tt> operators that are overloaded
309 to accept a <tt>char</tt> or <tt>wchar_t</tt> argument on its left or
310 right (but not both). An operator may be overloaded if at least one
311 of its parameters is a user-defined type. In this case, the
312 <tt>real_p</tt> is the 2nd argument to <tt>operator<span class=
313 "operators">&gt;&gt;</span></tt>, and so the proper overload of
314 <tt class="operators">&gt;&gt;</tt> is used, converting
315 <tt class="quotes">','</tt> into a character literal parser.<br>
316 <br>
317 The problem with omiting the <tt>ch_p</tt> call should be obvious:
318 <tt>'a' &gt;&gt; 'b'</tt> is <b>not</b> a spirit parser, it is a
319 numeric expression, right-shifting the ASCII (or another encoding)
320 value of <tt class="quotes">'a'</tt> by the ASCII value of
321 <tt class="quotes">'b'</tt>. However, both <tt>ch_p('a') &gt;&gt;
322 'b'</tt> and <tt>'a' &gt;&gt; ch_p('b')</tt> are Spirit sequence
323 parsers for the letter <tt class="quotes">'a'</tt> followed by
324 <tt class="quotes">'b'</tt>. You'll get used to it, sooner or
325 later.
326 </td>
327 </tr>
328 </table>
329 <p>
330 Take note that the object returned from the parse function has a member
331 called <tt>full</tt> which returns true if both of our requirements above
332 are met (i.e. the parser fully parsed the input).
333 </p>
334 <h4>
335 <b> Step 3. Semantic Actions</b></h4>
336 <p>
337 Our parser above is really nothing but a recognizer. It answers the
338 question <i class="quotes">"did the input match our grammar?"</i>, but it
339 does not remember any data, nor does it perform any side effects.
340 Remember: we want to put the parsed numbers into a vector. This is done
341 in an <b>action</b> that is linked to a particular parser. For example,
342 whenever we parse a real number, we wish to store the parsed number after
343 a successful match. We now wish to extract information from the parser.
344 Semantic actions do this. Semantic actions may be attached to any point
345 in the grammar specification. These actions are C++ functions or functors
346 that are called whenever a part of the parser successfully recognizes a
347 portion of the input. Say you have a parser <b>P</b>, and a C++ function
348 <b>F</b>, you can make the parser call <b>F</b> whenever it matches an
349 input by attaching <b>F</b>:
350 </p>
351
352<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
353"identifier">P</span><span class="special">[&amp;</span><span class=
354"identifier">F</span><span class="special">]</span></font></code>
355</pre>
356<p>
357 Or if <b>F</b> is a function object (a functor):
358 </p>
359
360<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
361"identifier">P</span><span class="special">[</span><span class=
362"identifier">F</span><span class="special">]</span></font></code>
363</pre>
364<p>
365 The function/functor signature depends on the type of the parser to which
366 it is attached. The parser <tt>real_p</tt> passes a single argument: the
367 parsed number. Thus, if we were to attach a function <b>F</b> to
368 <tt>real_p</tt>, we need <b>F</b> to be declared as:
369 </p>
370
371<pre><code> </code><code><span class=
372"keyword">void</span> <span class="identifier">F</span><span class=
373"special">(</span><span class="keyword">double</span> <span class=
374"identifier">n</span><span class="special">);</span></code></pre>
375<p>
376 For our example however, again, we can take advantage of some predefined
377 semantic functors and functor generators (<img src="theme/lens.gif"
378 width="15" height="16"> A functor generator is a function that returns
379 a functor). For our purpose, Spirit has a functor generator
380 <tt>push_back_a(c)</tt>. In brief, this semantic action, when called,
381 <b>appends</b> the parsed value it receives from the parser it is
382 attached to, to the container <tt>c</tt>.
383 </p>
384 <p>
385 Finally, here is our complete comma-separated list parser:
386 </p>
387
388<pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class=
389"keyword">bool
390</span> <span class="identifier">parse_numbers</span><span class=
391"special">(</span><span class="keyword">char</span> <span class=
392"keyword">const</span><span class="special">*</span> <span class=
393"identifier">str</span><span class="special">,</span> <span class=
394"identifier">vector</span><span class="special">&lt;</span><span class=
395"keyword">double</span><span class=
396 "special">&gt;&amp;</span> <span class="identifier">v</span><span class=
397 "special">)
398 {
399</span> <span class="keyword">return</span> <span class=
400"identifier">parse</span><span class="special">(</span><span class=
401"identifier">str</span><span class="special">,
402
403</span> <span class="comment"> // Begin grammar
404</span> <span class="special"> (
405</span> <span class="identifier">real_p</span><span class=
406"special">[</span><span class="identifier">push_back_a</span><span class=
407"special">(</span><span class="identifier">v</span><span class=
408"special">)]</span> <span class="special">&gt;&gt;</span> <span class=
409"special">*(</span><span class="literal">','</span> <span class=
410"special">&gt;&gt;</span> <span class=
411 "identifier">real_p</span><span class="special">[</span><span class=
412 "identifier">push_back_a</span><span class="special">(</span><span class=
413 "identifier">v</span><span class="special">)])
414 )
415</span> <span class="special"> ,
416</span> <span class="comment"> // End grammar
417
418</span> <span class="identifier"> space_p</span><span class=
419"special">).</span><span class="identifier">full</span><span class="special">;
420 }</span></font></code>
421</pre>
422<p>
423 This is the same parser as above. This time with appropriate semantic
424 actions attached to strategic places to extract the parsed numbers and
425 stuff them in the vector <tt>v</tt>. The parse_numbers function returns
426 true when successful.
427 </p>
428 <p>
429 <img src="theme/lens.gif" width="15" height="16"> The full source code
430 can be <a href="../example/fundamental/number_list.cpp">viewed here</a>.
431 This is part of the Spirit distribution.
432 </p>
433 <table border="0">
434 <tr>
435 <td width="10"></td>
436 <td width="30">
437 <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a>
438 </td>
439 <td width="30">
440 <a href="introduction.html"><img src="theme/l_arr.gif" border="0">
441 </a>
442 </td>
443 <td width="30">
444 <a href="basic_concepts.html"><img src="theme/r_arr.gif" border="0">
445 </a>
446 </td>
447 </tr>
448 </table><br>
449 <hr size="1">
450 <p class="copyright">
451 Copyright &copy; 1998-2003 Joel de Guzman<br>
452 Copyright &copy; 2002 Chris Uzdavinis<br>
453 <br>
454 <font size="2">Use, modification and distribution is subject to the
455 Boost Software License, Version 1.0. (See accompanying file
456 LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</font>
457 </p>
458 <blockquote>&nbsp;
459
460 </blockquote>
461 </body>
462</html>