libs/spirit/doc/html/spirit/karma/tutorials/warming_up.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Warming up</title>
   5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../../../index.html" title="Spirit 2.5.2">
   8 <link rel="up" href="../tutorials.html" title="Tutorials">
   9 <link rel="prev" href="quick_start.html" title="Quick Start">
  10 <link rel="next" href="semantic_actions.html" title="Generator Semantic Actions">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="quick_start.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="semantic_actions.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="spirit.karma.tutorials.warming_up"></a><a class="link" href="warming_up.html" title="Warming up">Warming up</a>
  28 </h4></div></div></div>
  29 <p>
  30           Learning how to use <span class="emphasis"><em>Spirit.Karma</em></span> is really simple.
  31           We will start from trivial examples, ramping up as we go.
  32         </p>
  33 <h6>
  34 <a name="spirit.karma.tutorials.warming_up.h0"></a>
  35           <span class="phrase"><a name="spirit.karma.tutorials.warming_up.trivial_example__1_generating_a_number"></a></span><a class="link" href="warming_up.html#spirit.karma.tutorials.warming_up.trivial_example__1_generating_a_number">Trivial
  36           Example #1 Generating a number</a>
  37         </h6>
  38 <p>
  39           Let's create a generator that will output a floating-point number:
  40         </p>
  41 <pre class="programlisting"><span class="identifier">double_</span>
  42 </pre>
  43 <p>
  44           Easy huh? The above code actually instantiates a Spirit floating point
  45           generator (a built-in generator). Spirit has many pre-defined generators
  46           and consistent naming conventions will help you finding your way through
  47           the maze. Especially important to note is that things related to identical
  48           entities (as in this case, floating point numbers) are named identically
  49           in <span class="emphasis"><em>Spirit.Karma</em></span> and in <span class="emphasis"><em>Spirit.Qi</em></span>.
  50           Actually, both libraries are using the very same variable instance to refer
  51           to a floating point generator or parser: <code class="computeroutput"><span class="identifier">double_</span></code>.
  52         </p>
  53 <h6>
  54 <a name="spirit.karma.tutorials.warming_up.h1"></a>
  55           <span class="phrase"><a name="spirit.karma.tutorials.warming_up.trivial_example__2_generating_two_numbers"></a></span><a class="link" href="warming_up.html#spirit.karma.tutorials.warming_up.trivial_example__2_generating_two_numbers">Trivial
  56           Example #2 Generating two numbers</a>
  57         </h6>
  58 <p>
  59           Now, let's create a generator that will output a line consisting of two
  60           floating-point numbers.
  61         </p>
  62 <pre class="programlisting"><span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span>
  63 </pre>
  64 <p>
  65           Here you see the familiar floating-point numeric generator <code class="computeroutput"><span class="identifier">double_</span></code> used twice, once for each number.
  66           If you are used to see the <code class="computeroutput"><span class="char">'&gt;&gt;'</span></code>
  67           operator for concatenating two parsers in <span class="emphasis"><em>Spirit.Qi</em></span>
  68           you might wonder, what's that <code class="computeroutput"><span class="char">'&lt;&lt;'</span></code>
  69           operator doing in there? We decided to distinguish generating and parsing
  70           of sequences the same way as the std::stream libraries do: we use operator
  71           <code class="computeroutput"><span class="char">'&gt;&gt;'</span></code> for input (parsing),
  72           and operator <code class="computeroutput"><span class="char">'&lt;&lt;'</span></code> for output
  73           (generating). Other than that there is no significant difference. The above
  74           program creates a generator from two simpler generators, glueing them together
  75           with the sequence operator. The result is a generator that is a composition
  76           of smaller generators. Whitespace between numbers can implicitly be inserted
  77           depending on how the generator is invoked (see below).
  78         </p>
  79 <div class="note"><table border="0" summary="Note">
  80 <tr>
  81 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td>
  82 <th align="left">Note</th>
  83 </tr>
  84 <tr><td align="left" valign="top"><p>
  85             When we combine generators, we end up with a "bigger" generator,
  86             but it's still a generator. Generators can get bigger and bigger, nesting
  87             more and more, but whenever you glue two generators together, you end
  88             up with one bigger generator. This is an important concept.
  89           </p></td></tr>
  90 </table></div>
  91 <h6>
  92 <a name="spirit.karma.tutorials.warming_up.h2"></a>
  93           <span class="phrase"><a name="spirit.karma.tutorials.warming_up.trivial_example__3_generating_one_or_more_numbers"></a></span><a class="link" href="warming_up.html#spirit.karma.tutorials.warming_up.trivial_example__3_generating_one_or_more_numbers">Trivial
  94           Example #3 Generating one or more numbers</a>
  95         </h6>
  96 <p>
  97           Now, creating output for two numbers is not too interesting. Let's create
  98           a generator that will output zero or more floating-point numbers in a row.
  99         </p>
 100 <pre class="programlisting"><span class="special">*</span><span class="identifier">double_</span>
 101 </pre>
 102 <p>
 103           This is like a regular-expression Kleene Star. We moved the <code class="computeroutput"><span class="special">*</span></code> to the front for the same reasons we did
 104           in <span class="emphasis"><em>Spirit.Qi</em></span>: we must work with the syntax rules of
 105           C++. But if you know regular expressions (and for sure you remember those
 106           C++ syntax rules) it will start to look very familiar in a matter of a
 107           very short time.
 108         </p>
 109 <p>
 110           Any expression that evaluates to a generator may be used with the Kleene
 111           Star. Keep in mind, though, that due to C++ operator precedence rules you
 112           may need to put the expression in parentheses for complex expressions.
 113           As above, whitespace can be inserted implicitly in between the generated
 114           numbers, if needed.
 115         </p>
 116 <h6>
 117 <a name="spirit.karma.tutorials.warming_up.h3"></a>
 118           <span class="phrase"><a name="spirit.karma.tutorials.warming_up.trivial_example__4_generating_a_comma_delimited_list_of_numbers"></a></span><a class="link" href="warming_up.html#spirit.karma.tutorials.warming_up.trivial_example__4_generating_a_comma_delimited_list_of_numbers">Trivial
 119           Example #4 Generating a comma-delimited list of numbers</a>
 120         </h6>
 121 <p>
 122           We follow the lead of <span class="emphasis"><em>Spirit.Qi</em></span>'s warming up section
 123           and will create a generator that produces a comma-delimited list of numbers.
 124         </p>
 125 <pre class="programlisting"><span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="special">*(</span><span class="identifier">lit</span><span class="special">(</span><span class="char">','</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span><span class="special">)</span>
 126 </pre>
 127 <p>
 128           Notice <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="char">','</span><span class="special">)</span></code>. It is
 129           a literal character generator that simply generates the comma <code class="computeroutput"><span class="char">','</span></code>. In this case, the Kleene Star is modifying
 130           a more complex generator, namely, the one generated by the expression:
 131         </p>
 132 <pre class="programlisting"><span class="special">(</span><span class="identifier">lit</span><span class="special">(</span><span class="char">','</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span><span class="special">)</span>
 133 </pre>
 134 <p>
 135           Note that this is a case where the parentheses are necessary. The Kleene
 136           Star encloses the complete expression above, repeating the whole pattern
 137           in the generated output zero or more times.
 138         </p>
 139 <h6>
 140 <a name="spirit.karma.tutorials.warming_up.h4"></a>
 141           <span class="phrase"><a name="spirit.karma.tutorials.warming_up.let_s_generate_"></a></span><a class="link" href="warming_up.html#spirit.karma.tutorials.warming_up.let_s_generate_">Let's
 142           Generate!</a>
 143         </h6>
 144 <p>
 145           We're done with defining the generator. All that's left is to invoke the
 146           generator to do its work. For now, we will use the <code class="computeroutput"><span class="identifier">generate_delimited</span></code>
 147           function. One overload of this function accepts four arguments:
 148         </p>
 149 <div class="orderedlist"><ol class="orderedlist" type="1">
 150 <li class="listitem">
 151               An output iterator accepting the generated characters
 152             </li>
 153 <li class="listitem">
 154               The generator expression
 155             </li>
 156 <li class="listitem">
 157               Another generator called the delimiting generator
 158             </li>
 159 <li class="listitem">
 160               The data to format and output
 161             </li>
 162 </ol></div>
 163 <p>
 164           While comparing this minimal example with an equivalent parser example
 165           we notice a significant difference. It is possible (and actually, it makes
 166           a lot of sense) to use a parser without creating any internal representation
 167           of the parsed input (i.e. without 'producing' any data from the parsed
 168           input). Using a parser in this mode checks the provided input against the
 169           given parser expression allowing to verify whether the input is parsable.
 170           For generators this mode doesn't make any sense. What is output generation
 171           without generating any output? So we always will have to supply the data
 172           the output should be generated from. In our example we supply a list of
 173           <code class="computeroutput"><span class="keyword">double</span></code> numbers as the last
 174           parameter to the function <code class="computeroutput"><span class="identifier">generate_delimited</span></code>
 175           (see code below).
 176         </p>
 177 <p>
 178           In this example, we wish to delimit the generated numbers by spaces. Another
 179           generator named <code class="computeroutput"><span class="identifier">space</span></code> is
 180           included in Spirit's repertoire of predefined generators. It is a very
 181           trivial generator that simply produces spaces. It is the equivalent to
 182           writing <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="char">' '</span><span class="special">)</span></code>, or simply
 183           <code class="computeroutput"><span class="char">' '</span></code>. It has been implemented
 184           for similarity with the corresponding predefined <code class="computeroutput"><span class="identifier">space</span></code>
 185           parser. We will use <code class="computeroutput"><span class="identifier">space</span></code>
 186           as our delimiter. The delimiter is the one responsible for inserting characters
 187           in between generator elements such as the <code class="computeroutput"><span class="identifier">double_</span></code>
 188           and <code class="computeroutput"><span class="identifier">lit</span></code>.
 189         </p>
 190 <p>
 191           Ok, so now let's generate (for the complete source code of this example
 192           please refer to <a href="../../../../../example/karma/num_list1.cpp" target="_top">num_list1.cpp</a>).
 193         </p>
 194 <p>
 195 </p>
 196 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span>
 197 <span class="keyword">bool</span> <span class="identifier">generate_numbers</span><span class="special">(</span><span class="identifier">OutputIterator</span><span class="special">&amp;</span> <span class="identifier">sink</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">)</span>
 198 <span class="special">{</span>
 199     <span class="keyword">using</span> <span class="identifier">karma</span><span class="special">::</span><span class="identifier">double_</span><span class="special">;</span>
 200     <span class="keyword">using</span> <span class="identifier">karma</span><span class="special">::</span><span class="identifier">generate_delimited</span><span class="special">;</span>
 201     <span class="keyword">using</span> <span class="identifier">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span>
 202
 203     <span class="keyword">bool</span> <span class="identifier">r</span> <span class="special">=</span> <span class="identifier">generate_delimited</span><span class="special">(</span>
 204         <span class="identifier">sink</span><span class="special">,</span>                           <span class="comment">// destination: output iterator</span>
 205         <span class="identifier">double_</span> <span class="special">&lt;&lt;</span> <span class="special">*(</span><span class="char">','</span> <span class="special">&lt;&lt;</span> <span class="identifier">double_</span><span class="special">),</span>   <span class="comment">// the generator</span>
 206         <span class="identifier">space</span><span class="special">,</span>                          <span class="comment">// the delimiter-generator</span>
 207         <span class="identifier">v</span>                               <span class="comment">// the data to output </span>
 208     <span class="special">);</span>
 209     <span class="keyword">return</span> <span class="identifier">r</span><span class="special">;</span>
 210 <span class="special">}</span>
 211 </pre>
 212 <p>
 213         </p>
 214 <div class="note"><table border="0" summary="Note">
 215 <tr>
 216 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td>
 217 <th align="left">Note</th>
 218 </tr>
 219 <tr><td align="left" valign="top"><p>
 220             You might wonder how a <code class="computeroutput"><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span></code>, which is actually a single data
 221             structure, can be used as an argument (we call it attribute) to a sequence
 222             of generators. This seems to be counter intuitive and doesn't match with
 223             your experience of using <code class="computeroutput"><span class="identifier">printf</span></code>,
 224             where each formatting placeholder has to be matched with a corresponding
 225             argument. Well, we will explain this behavior in more detail later in
 226             this tutorial. For now just consider this to be a special case, implemented
 227             on purpose to allow more flexible output formatting of STL containers:
 228             sequences accept a single container attribute if all elements of this
 229             sequence accept attributes compatible with the elements held by this
 230             container.
 231           </p></td></tr>
 232 </table></div>
 233 <p>
 234           The generate function returns <code class="computeroutput"><span class="keyword">true</span></code>
 235           or <code class="computeroutput"><span class="keyword">false</span></code> depending on the
 236           result of the output generation. As outlined in different places of this
 237           documentation, a generator may fail for different reasons. One of the possible
 238           reasons is an error in the underlying output iterator (memory exhausted
 239           or disk full, etc.). Another reason might be that the data doesn't match
 240           the requirements of a particular generator.
 241         </p>
 242 <div class="note"><table border="0" summary="Note">
 243 <tr>
 244 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td>
 245 <th align="left">Note</th>
 246 </tr>
 247 <tr><td align="left" valign="top">
 248 <p>
 249             <code class="computeroutput"><span class="keyword">char</span></code> and <code class="computeroutput"><span class="keyword">wchar_t</span></code>
 250             operands
 251           </p>
 252 <p>
 253             The careful reader may notice that the generator expression has <code class="computeroutput"><span class="char">','</span></code> instead of <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="char">','</span><span class="special">)</span></code>
 254             as the previous examples did. This is ok due to C++ syntax rules of conversion.
 255             Spirit provides <code class="computeroutput"><span class="special">&lt;&lt;</span></code>
 256             operators that are overloaded to accept a <code class="computeroutput"><span class="keyword">char</span></code>
 257             or <code class="computeroutput"><span class="keyword">wchar_t</span></code> argument on its
 258             left or right (but not both). An operator may be overloaded if at least
 259             one of its parameters is a user-defined type. In this case, the <code class="computeroutput"><span class="identifier">double_</span></code> is the 2nd argument to <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code>,
 260             and so the proper overload of <code class="computeroutput"><span class="special">&lt;&lt;</span></code>
 261             is used, converting <code class="computeroutput"><span class="char">','</span></code> into
 262             a character literal generator.
 263           </p>
 264 <p>
 265             The problem with omitting the <code class="computeroutput"><span class="identifier">lit</span></code>
 266             should be obvious: <code class="computeroutput"><span class="char">'a'</span> <span class="special">&lt;&lt;</span>
 267             <span class="char">'b'</span></code> is not a spirit generator, it
 268             is a numeric expression, left-shifting the ASCII (or another encoding)
 269             value of <code class="computeroutput"><span class="char">'a'</span></code> by the ASCII value
 270             of <code class="computeroutput"><span class="char">'b'</span></code>. However, both <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="char">'a'</span><span class="special">)</span> <span class="special">&lt;&lt;</span>
 271             <span class="char">'b'</span></code> and <code class="computeroutput"><span class="char">'a'</span>
 272             <span class="special">&lt;&lt;</span> <span class="identifier">lit</span><span class="special">(</span><span class="char">'b'</span><span class="special">)</span></code>
 273             are Spirit sequence generators for the letter <code class="computeroutput"><span class="char">'a'</span></code>
 274             followed by <code class="computeroutput"><span class="char">'b'</span></code>. You'll get
 275             used to it, sooner or later.
 276           </p>
 277 </td></tr>
 278 </table></div>
 279 <p>
 280           Note that we inlined the generator directly in the call to <code class="computeroutput"><span class="identifier">generate_delimited</span></code>. Upon calling this
 281           function, the expression evaluates into a temporary, unnamed generator
 282           which is passed into the <code class="computeroutput"><span class="identifier">generate_delimited</span></code>
 283           function, used, and then destroyed.
 284         </p>
 285 <p>
 286           Here, we chose to make the generate function generic by making it a template,
 287           parameterized by the output iterator type. By doing so, it can put the
 288           generated data into any STL conforming output iterator.
 289         </p>
 290 </div>
 291 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 292 <td align="left"></td>
 293 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 294         Distributed under the Boost Software License, Version 1.0. (See accompanying
 295         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 296       </p>
 297 </div></td>
 298 </tr></table>
 299 <hr>
 300 <div class="spirit-nav">
 301 <a accesskey="p" href="quick_start.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tutorials.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="semantic_actions.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 302 </div>
 303 </body>
 304 </html>