| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta content= |
| "HTML Tidy for Windows (vers 1st February 2003), see www.w3.org" |
| name="generator"> |
| <title> |
| Quick Start |
| </title> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <link rel="stylesheet" href="theme/style.css" type="text/css"> |
| </head> |
| <body> |
| <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2"> |
| <tr> |
| <td width="10"></td> |
| <td width="85%"> |
| <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Quick |
| Start</b></font> |
| </td> |
| <td width="112"> |
| <a href="http://spirit.sf.net"><img src="theme/spirit.gif" |
| width="112" height="48" align="right" border="0"></a> |
| </td> |
| </tr> |
| </table><br> |
| <table border="0"> |
| <tr> |
| <td width="10"></td> |
| <td width="30"> |
| <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a> |
| </td> |
| <td width="30"> |
| <a href="introduction.html"><img src="theme/l_arr.gif" border="0"> |
| </a> |
| </td> |
| <td width="30"> |
| <a href="basic_concepts.html"><img src="theme/r_arr.gif" border="0"> |
| </a> |
| </td> |
| </tr> |
| </table> |
| <h2> |
| <b>Why would you want to use Spirit?</b> |
| </h2> |
| <p> |
| Spirit is designed to be a practical parsing tool. At the very least, the |
| ability to generate a fully-working parser from a formal EBNF |
| specification inlined in C++ significantly reduces development time. |
| While it may be practical to use a full-blown, stand-alone parser such as |
| YACC or ANTLR when we want to develop a computer language such as C or |
| Pascal, it is certainly overkill to bring in the big guns when we wish to |
| write extremely small micro-parsers. At that end of the spectrum, |
| programmers typically approach the job at hand not as a formal parsing |
| task but through ad hoc hacks using primitive tools such as |
| <tt>scanf</tt>. True, there are tools such as regular-expression |
| libraries (such as <a href= |
| "http://www.boost.org/libs/regex/index.html">boost regex</a>) or scanners |
| (such as <a href="http://www.boost.org/libs/tokenizer/index.html">boost |
| tokenizer</a>), but these tools do not scale well when we need to write |
| more elaborate parsers. Attempting to write even a moderately-complex |
| parser using these tools leads to code that is hard to understand and |
| maintain. |
| </p> |
| <p> |
| One prime objective is to make the tool easy to use. When one thinks of a |
| parser generator, the usual reaction is "it must be big and complex with |
| a steep learning curve." Not so. Spirit is designed to be fully scalable. |
| The framework is structured in layers. This permits learning on an |
| as-needed basis, after only learning the minimal core and basic concepts. |
| </p> |
| <p> |
| For development simplicity and ease in deployment, the entire framework |
| consists of only header files, with no libraries to link against or |
| build. Just put the spirit distribution in your include path, compile and |
| run. Code size? -very tight. In the quick start example that we shall |
| present in a short while, the code size is dominated by the instantiation |
| of the <tt>std::vector</tt> and <tt>std::iostream</tt>. |
| </p> |
| <h2> |
| <b>Trivial Example #1</b></h2> |
| <p>Create a parser that will parse |
| a floating-point number. |
| </p> |
| <pre><code><font color="#000000"> </font></code><span class="identifier">real_p</span> |
| </pre> |
| <p> |
| (You've got to admit, that's trivial!) The above code actually generates |
| a Spirit <tt>real_parser</tt> (a built-in parser) which parses a floating |
| point number. Take note that parsers that are meant to be used directly |
| by the user end with "<tt>_p</tt>" in their names as a Spirit convention. |
| Spirit has many pre-defined parsers and consistent naming conventions |
| help you keep from going insane! |
| </p> |
| <h2> |
| <b>Trivial Example #2</b></h2> |
| <p> |
| Create a parser that will accept a line consisting of two floating-point |
| numbers. |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><span class= |
| "identifier">real_p</span> <span class= |
| "special">>></span> <span class="identifier">real_p</span></code> |
| </pre> |
| <p> |
| Here you see the familiar floating-point numeric parser |
| <code><tt>real_p</tt></code> used twice, once for each number. What's |
| that <tt class="operators">>></tt> operator doing in there? Well, |
| they had to be separated by something, and this was chosen as the |
| "followed by" sequence operator. The above program creates a parser from |
| two simpler parsers, glueing them together with the sequence operator. |
| The result is a parser that is a composition of smaller parsers. |
| Whitespace between numbers can implicitly be consumed depending on how |
| the parser is invoked (see below). |
| </p> |
| <p> |
| Note: when we combine parsers, we end up with a "bigger" parser, But it's |
| still a parser. Parsers can get bigger and bigger, nesting more and more, |
| but whenever you glue two parsers together, you end up with one bigger |
| parser. This is an important concept. |
| </p> |
| <h2> |
| <b>Trivial Example #3</b></h2> |
| <p> |
| Create a parser that will accept an arbitrary number of floating-point |
| numbers. (Arbitrary means anything from zero to infinity) |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><span class= |
| "special">*</span><span class="identifier">real_p</span></code> |
| </pre> |
| <p> |
| This is like a regular-expression Kleene Star, though the syntax might |
| look a bit odd for a C++ programmer not used to seeing the <tt class= |
| "operators">*</tt> operator overloaded like this. Actually, if you know |
| regular expressions it may look odd too since the star is <b>before</b> |
| the expression it modifies. C'est la vie. Blame it on the fact that we |
| must work with the syntax rules of C++. |
| </p> |
| <p> |
| Any expression that evaluates to a parser may be used with the Kleene |
| Star. Keep in mind, though, that due to C++ operator precedence rules you |
| may need to put the expression in parentheses for complex expressions. |
| The Kleene Star is also known as a Kleene Closure, but we call it the |
| Star in most places. |
| </p> |
| <h3> |
| <b><a name="list_of_numbers"></a> Example #4 [ A Just Slightly Less Trivial Example</b> |
| ] </h3> |
| <p> |
| This example will create a parser that accepts a comma-delimited list of numbers and put the numbers in a vector. |
| </p> |
| <h4><strong> Step 1. Create the parser</strong></h4> |
| <pre><code><font color="#000000"> </font></code><code><span class= |
| "identifier">real_p</span> <span class= |
| "special">>></span> <span class="special">*(</span><span class= |
| "identifier">ch_p</span><span class="special">(</span><span class= |
| "literal">','</span><span class="special">)</span> <span class= |
| "special">>></span> <span class= |
| "identifier">real_p</span><span class="special">)</span></code> |
| </pre> |
| <p> |
| Notice <tt>ch_p(',')</tt>. It is a literal character parser that can |
| recognize the comma <tt>','</tt>. In this case, the Kleene Star is |
| modifying a more complex parser, namely, the one generated by the |
| expression: |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><span class= |
| "special">(</span><span class="identifier">ch_p</span><span class= |
| "special">(</span><span class="literal">','</span><span class= |
| "special">)</span> <span class="special">>></span> <span class= |
| "identifier">real_p</span><span class="special">)</span></code> |
| </pre> |
| <p> |
| Note that this is a case where the parentheses are necessary. The Kleene |
| star encloses the complete expression above. |
| </p> |
| <h4> |
| <b><strong>Step 2. </strong>Using a Parser (now that it's created)</b></h4> |
| <p> |
| Now that we have created a parser, how do we use it? Like the result of |
| any C++ temporary object, we can either store it in a variable, or call |
| functions directly on it. |
| </p> |
| <p> |
| We'll gloss over some low-level C++ details and just get to the good |
| stuff. |
| </p> |
| <p> |
| If <b><tt>r</tt></b> is a rule (don't worry about what rules exactly are |
| for now. This will be discussed later. Suffice it to say that the rule is |
| a placeholder variable that can hold a parser), then we store the parser |
| as a rule like this: |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "identifier">r</span> <span class="special">=</span> <span class= |
| "identifier">real_p</span> <span class= |
| "special">>> *(</span><span class= |
| "identifier">ch_p</span><span class="special">(</span><span class= |
| "literal">','</span><span class="special">) >></span> <span class= |
| "identifier">real_p</span><span class="special">);</span></font></code> |
| </pre> |
| <p> |
| Not too exciting, just an assignment like any other C++ expression you've |
| used for years. The cool thing about storing a parser in a rule is this: |
| rules are parsers, and now you can refer to it <b>by name</b>. (In this |
| case the name is <tt><b>r</b></tt>). Notice that this is now a full |
| assignment expression, thus we terminate it with a semicolon, |
| "<tt>;</tt>". |
| </p> |
| <p> |
| That's it. We're done with defining the parser. So the next step is now |
| invoking this parser to do its work. There are a couple of ways to do |
| this. For now, we shall use the free <tt>parse</tt> function that takes |
| in a <tt>char const*</tt>. The function accepts three arguments: |
| </p> |
| <blockquote> |
| <p> |
| <img src="theme/bullet.gif" width="12" height="12"> The null-terminated |
| <tt>const char*</tt> input<br> |
| <img src="theme/bullet.gif" width="12" height="12"> The parser |
| object<br> |
| <img src="theme/bullet.gif" width="12" height="12"> Another parser |
| called the <b>skip parser</b> |
| </p> |
| </blockquote> |
| <p> |
| In our example, we wish to skip spaces and tabs. Another parser named |
| <tt>space_p</tt> is included in Spirit's repertoire of predefined |
| parsers. It is a very simple parser that simply recognizes whitespace. We |
| shall use <tt>space_p</tt> as our skip parser. The skip parser is the one |
| responsible for skipping characters in between parser elements such as |
| the <tt>real_p</tt> and the <tt>ch_p</tt>. |
| </p> |
| <p> |
| Ok, so now let's parse! |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "identifier">r</span> <span class="special">=</span> <span class= |
| "identifier">real_p</span> <span class= |
| "special">>></span> <span class="special">*(</span><span class= |
| "identifier">ch_p</span><span class="special">(</span><span class= |
| "literal">','</span><span class="special">)</span> <span class= |
| "special">>></span> <span class= |
| "identifier">real_p</span><span class="special">); |
| </span> <span class="identifier"> parse</span><span class= |
| "special">(</span><span class="identifier">str</span><span class= |
| "special">,</span> <span class="identifier">r</span><span class= |
| "special">,</span> <span class="identifier">space_p</span><span class= |
| "special">)</span> <span class= |
| "comment">// Not a full statement yet, patience...</span></font></code> |
| </pre> |
| <p> |
| The parse function returns an object (called <tt>parse_info</tt>) that |
| holds, among other things, the result of the parse. In this example, we |
| need to know: |
| </p> |
| <blockquote> |
| <p> |
| <img src="theme/bullet.gif" width="12" height="12"> Did the parser |
| successfully recognize the input <tt>str</tt>?<br> |
| <img src="theme/bullet.gif" width="12" height="12"> Did the parser |
| <b>fully</b> parse and consume the input up to its end? |
| </p> |
| </blockquote> |
| <p> |
| To get a complete picture of what we have so far, let us also wrap this |
| parser inside a function: |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "keyword">bool |
| </span> <span class="identifier"> parse_numbers</span><span class= |
| "special">(</span><span class="keyword">char</span> <span class= |
| "keyword">const</span><span class="special">*</span> <span class= |
| "identifier">str</span><span class="special">) |
| { |
| </span> <span class="keyword"> return</span> <span class= |
| "identifier">parse</span><span class="special">(</span><span class= |
| "identifier">str</span><span class="special">,</span> <span class= |
| "identifier">real_p</span> <span class= |
| "special">>></span> <span class="special">*(</span><span class= |
| "literal">','</span> <span class="special">>></span> <span class= |
| "identifier">real_p</span><span class="special">),</span> <span class= |
| "identifier">space_p</span><span class="special">).</span><span class= |
| "identifier">full</span><span class="special">; |
| }</span></font></code> |
| </pre> |
| <p> |
| Note in this case we dropped the named rule and inlined the parser |
| directly in the call to parse. Upon calling parse, the expression |
| evaluates into a temporary, unnamed parser which is passed into the |
| parse() function, used, and then destroyed. |
| </p> |
| <table border="0" width="80%" align="center"> |
| <tr> |
| <td class="note_box"> |
| <img src="theme/note.gif" width="16" height="16"><b>char and wchar_t |
| operands</b><br> |
| <br> |
| The careful reader may notice that the parser expression has |
| <tt class="quotes">','</tt> instead of <tt>ch_p(',')</tt> as the |
| previous examples did. This is ok due to C++ syntax rules of |
| conversion. There are <tt>>></tt> operators that are overloaded |
| to accept a <tt>char</tt> or <tt>wchar_t</tt> argument on its left or |
| right (but not both). An operator may be overloaded if at least one |
| of its parameters is a user-defined type. In this case, the |
| <tt>real_p</tt> is the 2nd argument to <tt>operator<span class= |
| "operators">>></span></tt>, and so the proper overload of |
| <tt class="operators">>></tt> is used, converting |
| <tt class="quotes">','</tt> into a character literal parser.<br> |
| <br> |
| The problem with omiting the <tt>ch_p</tt> call should be obvious: |
| <tt>'a' >> 'b'</tt> is <b>not</b> a spirit parser, it is a |
| numeric expression, right-shifting the ASCII (or another encoding) |
| value of <tt class="quotes">'a'</tt> by the ASCII value of |
| <tt class="quotes">'b'</tt>. However, both <tt>ch_p('a') >> |
| 'b'</tt> and <tt>'a' >> ch_p('b')</tt> are Spirit sequence |
| parsers for the letter <tt class="quotes">'a'</tt> followed by |
| <tt class="quotes">'b'</tt>. You'll get used to it, sooner or |
| later. |
| </td> |
| </tr> |
| </table> |
| <p> |
| Take note that the object returned from the parse function has a member |
| called <tt>full</tt> which returns true if both of our requirements above |
| are met (i.e. the parser fully parsed the input). |
| </p> |
| <h4> |
| <b> Step 3. Semantic Actions</b></h4> |
| <p> |
| Our parser above is really nothing but a recognizer. It answers the |
| question <i class="quotes">"did the input match our grammar?"</i>, but it |
| does not remember any data, nor does it perform any side effects. |
| Remember: we want to put the parsed numbers into a vector. This is done |
| in an <b>action</b> that is linked to a particular parser. For example, |
| whenever we parse a real number, we wish to store the parsed number after |
| a successful match. We now wish to extract information from the parser. |
| Semantic actions do this. Semantic actions may be attached to any point |
| in the grammar specification. These actions are C++ functions or functors |
| that are called whenever a part of the parser successfully recognizes a |
| portion of the input. Say you have a parser <b>P</b>, and a C++ function |
| <b>F</b>, you can make the parser call <b>F</b> whenever it matches an |
| input by attaching <b>F</b>: |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "identifier">P</span><span class="special">[&</span><span class= |
| "identifier">F</span><span class="special">]</span></font></code> |
| </pre> |
| <p> |
| Or if <b>F</b> is a function object (a functor): |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "identifier">P</span><span class="special">[</span><span class= |
| "identifier">F</span><span class="special">]</span></font></code> |
| </pre> |
| <p> |
| The function/functor signature depends on the type of the parser to which |
| it is attached. The parser <tt>real_p</tt> passes a single argument: the |
| parsed number. Thus, if we were to attach a function <b>F</b> to |
| <tt>real_p</tt>, we need <b>F</b> to be declared as: |
| </p> |
| |
| <pre><code> </code><code><span class= |
| "keyword">void</span> <span class="identifier">F</span><span class= |
| "special">(</span><span class="keyword">double</span> <span class= |
| "identifier">n</span><span class="special">);</span></code></pre> |
| <p> |
| For our example however, again, we can take advantage of some predefined |
| semantic functors and functor generators (<img src="theme/lens.gif" |
| width="15" height="16"> A functor generator is a function that returns |
| a functor). For our purpose, Spirit has a functor generator |
| <tt>push_back_a(c)</tt>. In brief, this semantic action, when called, |
| <b>appends</b> the parsed value it receives from the parser it is |
| attached to, to the container <tt>c</tt>. |
| </p> |
| <p> |
| Finally, here is our complete comma-separated list parser: |
| </p> |
| |
| <pre><code><font color="#000000"> </font></code><code><font color="#000000"><span class= |
| "keyword">bool |
| </span> <span class="identifier">parse_numbers</span><span class= |
| "special">(</span><span class="keyword">char</span> <span class= |
| "keyword">const</span><span class="special">*</span> <span class= |
| "identifier">str</span><span class="special">,</span> <span class= |
| "identifier">vector</span><span class="special"><</span><span class= |
| "keyword">double</span><span class= |
| "special">>&</span> <span class="identifier">v</span><span class= |
| "special">) |
| { |
| </span> <span class="keyword">return</span> <span class= |
| "identifier">parse</span><span class="special">(</span><span class= |
| "identifier">str</span><span class="special">, |
| |
| </span> <span class="comment"> // Begin grammar |
| </span> <span class="special"> ( |
| </span> <span class="identifier">real_p</span><span class= |
| "special">[</span><span class="identifier">push_back_a</span><span class= |
| "special">(</span><span class="identifier">v</span><span class= |
| "special">)]</span> <span class="special">>></span> <span class= |
| "special">*(</span><span class="literal">','</span> <span class= |
| "special">>></span> <span class= |
| "identifier">real_p</span><span class="special">[</span><span class= |
| "identifier">push_back_a</span><span class="special">(</span><span class= |
| "identifier">v</span><span class="special">)]) |
| ) |
| </span> <span class="special"> , |
| </span> <span class="comment"> // End grammar |
| |
| </span> <span class="identifier"> space_p</span><span class= |
| "special">).</span><span class="identifier">full</span><span class="special">; |
| }</span></font></code> |
| </pre> |
| <p> |
| This is the same parser as above. This time with appropriate semantic |
| actions attached to strategic places to extract the parsed numbers and |
| stuff them in the vector <tt>v</tt>. The parse_numbers function returns |
| true when successful. |
| </p> |
| <p> |
| <img src="theme/lens.gif" width="15" height="16"> The full source code |
| can be <a href="../example/fundamental/number_list.cpp">viewed here</a>. |
| This is part of the Spirit distribution. |
| </p> |
| <table border="0"> |
| <tr> |
| <td width="10"></td> |
| <td width="30"> |
| <a href="../index.html"><img src="theme/u_arr.gif" border="0"></a> |
| </td> |
| <td width="30"> |
| <a href="introduction.html"><img src="theme/l_arr.gif" border="0"> |
| </a> |
| </td> |
| <td width="30"> |
| <a href="basic_concepts.html"><img src="theme/r_arr.gif" border="0"> |
| </a> |
| </td> |
| </tr> |
| </table><br> |
| <hr size="1"> |
| <p class="copyright"> |
| Copyright © 1998-2003 Joel de Guzman<br> |
| Copyright © 2002 Chris Uzdavinis<br> |
| <br> |
| <font size="2">Use, modification and distribution is subject to the |
| Boost Software License, Version 1.0. (See accompanying file |
| LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)</font> |
| </p> |
| <blockquote> |
| |
| </blockquote> |
| </body> |
| </html> |
