1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.79.1"> 7<link rel="home" href="../../../index.html" title="Spirit 2.5.8"> 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"><<</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">'>>'</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">'<<'</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">'>>'</span></code> for input (parsing), 72 and operator <code class="computeroutput"><span class="char">'<<'</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"><<</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"><<</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"><<</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"><</span><span class="keyword">typename</span> <span class="identifier">OutputIterator</span><span class="special">></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">&</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"><</span><span class="keyword">double</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</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"><<</span> <span class="special">*(</span><span class="char">','</span> <span class="special"><<</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"><</span><span class="keyword">double</span><span class="special">></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"><<</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"><<</span></code>, 260 and so the proper overload of <code class="computeroutput"><span class="special"><<</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"><<</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"><<</span> 271 <span class="char">'b'</span></code> and <code class="computeroutput"><span class="char">'a'</span> 272 <span class="special"><<</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 © 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> 305
