1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Generator Semantic Actions</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="warming_up.html" title="Warming up"> 10<link rel="next" href="karma_complex.html" title="Complex - A first more complex generator"> 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="warming_up.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="karma_complex.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.semantic_actions"></a><a class="link" href="semantic_actions.html" title="Generator Semantic Actions">Generator 28 Semantic Actions</a> 29</h4></div></div></div> 30<p> 31 In the previous section we mentioned a very important difference between 32 parsers and generators. While parsers may be used without 'producing' any 33 data, generators always need data to generate the output from. We mentioned 34 one way of passing data to the generator by supplying it as a parameter 35 to one of the main API functions (for instance <code class="computeroutput"><span class="identifier">generate</span><span class="special">()</span></code> or <code class="computeroutput"><span class="identifier">generate_delimited</span><span class="special">()</span></code>). But sometimes this is not possible 36 or not desirable. 37 </p> 38<p> 39 Very much like for <span class="emphasis"><em>Spirit.Qi</em></span> we have semantic actions 40 in <span class="emphasis"><em>Spirit.Karma</em></span> as well. Semantic actions may be attached 41 to any point in the grammar specification. These actions are C++ functions 42 or function objects that are called whenever a part of the generator is 43 about to be invoked. Say you have a generator <code class="computeroutput"><span class="identifier">G</span></code>, 44 and a C++ function <code class="computeroutput"><span class="identifier">F</span></code>, you 45 can make the generator call <code class="computeroutput"><span class="identifier">F</span></code> 46 just before it gets invoked by attaching <code class="computeroutput"><span class="identifier">F</span></code>: 47 </p> 48<pre class="programlisting"><span class="identifier">G</span><span class="special">[</span><span class="identifier">F</span><span class="special">]</span> 49</pre> 50<p> 51 The expression above links <code class="computeroutput"><span class="identifier">F</span></code> 52 to the generator, <code class="computeroutput"><span class="identifier">G</span></code>. 53 </p> 54<p> 55 Semantic actions in <span class="emphasis"><em>Spirit.Qi</em></span> are invoked after a 56 parser successfully matches its input and the matched value is passed into 57 the semantic action. In <span class="emphasis"><em>Spirit.Karma</em></span> the opposite 58 happens. Semantic actions are called before its associated generator is 59 invoked. They may provide the data required by the generator. 60 </p> 61<p> 62 The function/function object signature depends on the type of the generator 63 to which it is attached. The generator <code class="computeroutput"><span class="identifier">double_</span></code> 64 expects the number to generate. Thus, if we were to attach a function 65 <code class="computeroutput"><span class="identifier">F</span></code> to <code class="computeroutput"><span class="identifier">double_</span></code>, 66 we need <code class="computeroutput"><span class="identifier">F</span></code> to be declared 67 as: 68 </p> 69<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">F</span><span class="special">(</span><span class="keyword">double</span><span class="special">&</span> <span class="identifier">n</span><span class="special">);</span> 70</pre> 71<p> 72 where the function is expected to initialize the parameter <code class="computeroutput"><span class="identifier">n</span></code> with the value to generate. 73 </p> 74<div class="important"><table border="0" summary="Important"> 75<tr> 76<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../images/important.png"></td> 77<th align="left">Important</th> 78</tr> 79<tr><td align="left" valign="top"> 80<p> 81 Generally, and more formally, the semantic action <code class="computeroutput"><span class="identifier">F</span></code> 82 attached to a generator <code class="computeroutput"><span class="identifier">G</span></code> 83 needs to take a reference to the generator's attribute type as its first 84 parameter. For more information about generator attributes please see 85 the section Generator Attributes. 86 </p> 87<p> 88 In the example above the function F takes a <code class="computeroutput"><span class="keyword">double</span><span class="special">&</span></code> as its first parameter as the attribute 89 of the <code class="computeroutput"><span class="identifier">double_</span></code> generator 90 happens to be a <code class="computeroutput"><span class="keyword">double</span></code>. 91 </p> 92</td></tr> 93</table></div> 94<p> 95 There are actually 2 more arguments being passed (the generator context 96 and a reference to a boolean 'pass' parameter). We don't need these, for 97 now, but we'll see more on these other arguments later. <span class="emphasis"><em>Spirit.Karma</em></span> 98 allows us to bind a single argument function, like above. The other arguments 99 are simply ignored. 100 </p> 101<p> 102 To sum up, the possible signatures for semantic actions are: 103 </p> 104<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&);</span> 105<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&,</span> <span class="identifier">Context</span><span class="special">&);</span> 106<span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&,</span> <span class="identifier">Context</span><span class="special">&,</span> <span class="keyword">bool</span><span class="special">&);</span> 107</pre> 108<h6> 109<a name="spirit.karma.tutorials.semantic_actions.h0"></a> 110 <span class="phrase"><a name="spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions"></a></span><a class="link" href="semantic_actions.html#spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions">Examples 111 of Semantic Actions</a> 112 </h6> 113<p> 114 In the following example we present various ways to attach semantic actions: 115 </p> 116<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 117<li class="listitem"> 118 Using a plain function pointer 119 </li> 120<li class="listitem"> 121 Using a simple function object 122 </li> 123<li class="listitem"> 124 Using <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a> with 125 a plain function 126 </li> 127<li class="listitem"> 128 Using <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a> with 129 a member function 130 </li> 131<li class="listitem"> 132 Using <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a> 133 </li> 134</ul></div> 135<p> 136 Let's assume we have: 137 </p> 138<p> 139</p> 140<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">client</span> 141<span class="special">{</span> 142 <span class="keyword">namespace</span> <span class="identifier">karma</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">;</span> 143 144 <span class="comment">// A plain function</span> 145 <span class="keyword">void</span> <span class="identifier">read_function</span><span class="special">(</span><span class="keyword">int</span><span class="special">&</span> <span class="identifier">i</span><span class="special">)</span> 146 <span class="special">{</span> 147 <span class="identifier">i</span> <span class="special">=</span> <span class="number">42</span><span class="special">;</span> 148 <span class="special">}</span> 149 150 <span class="comment">// A member function</span> 151 <span class="keyword">struct</span> <span class="identifier">reader</span> 152 <span class="special">{</span> 153 <span class="keyword">void</span> <span class="identifier">print</span><span class="special">(</span><span class="keyword">int</span><span class="special">&</span> <span class="identifier">i</span><span class="special">)</span> <span class="keyword">const</span> 154 <span class="special">{</span> 155 <span class="identifier">i</span> <span class="special">=</span> <span class="number">42</span><span class="special">;</span> 156 <span class="special">}</span> 157 <span class="special">};</span> 158 159 <span class="comment">// A function object</span> 160 <span class="keyword">struct</span> <span class="identifier">read_action</span> 161 <span class="special">{</span> 162 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span><span class="special">&</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">unused_type</span><span class="special">,</span> <span class="identifier">unused_type</span><span class="special">)</span> <span class="keyword">const</span> 163 <span class="special">{</span> 164 <span class="identifier">i</span> <span class="special">=</span> <span class="number">42</span><span class="special">;</span> 165 <span class="special">}</span> 166 <span class="special">};</span> 167<span class="special">}</span> 168</pre> 169<p> 170 </p> 171<p> 172 Take note that with function objects, we need to have an <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code> 173 with 3 arguments. Since we don't care about the other two, we can use 174 <code class="computeroutput"><span class="identifier">unused_type</span></code> for these. 175 We'll see more of <code class="computeroutput"><span class="identifier">unused_type</span></code> 176 elsewhere. Get used to it. <code class="computeroutput"><span class="identifier">unused_type</span></code> 177 is a Spirit supplied support class. Most of the time it stands for 'I don't 178 care, just use the appropriate default'. 179 </p> 180<p> 181 All following examples generate outputs of the form: 182 </p> 183<pre class="programlisting"><span class="string">"{integer}"</span> 184</pre> 185<p> 186 An integer inside the curly braces. 187 </p> 188<p> 189 The first example shows how to attach a plain function: 190 </p> 191<p> 192</p> 193<pre class="programlisting"><span class="identifier">generate</span><span class="special">(</span><span class="identifier">outiter</span><span class="special">,</span> <span class="char">'{'</span> <span class="special"><<</span> <span class="identifier">int_</span><span class="special">[&</span><span class="identifier">read_function</span><span class="special">]</span> <span class="special"><<</span> <span class="char">'}'</span><span class="special">);</span> 194</pre> 195<p> 196 </p> 197<p> 198 What's new? Well <code class="computeroutput"><span class="identifier">int_</span></code> is 199 the sibling of <code class="computeroutput"><span class="identifier">double_</span></code>. 200 I'm sure you can guess what this generator does and what type of attribute 201 it expects. 202 </p> 203<p> 204 The next example shows how to attach a simple function object: 205 </p> 206<p> 207</p> 208<pre class="programlisting"><span class="identifier">generate</span><span class="special">(</span><span class="identifier">outiter</span><span class="special">,</span> <span class="char">'{'</span> <span class="special"><<</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">read_action</span><span class="special">()]</span> <span class="special"><<</span> <span class="char">'}'</span><span class="special">);</span> 209</pre> 210<p> 211 </p> 212<p> 213 We can use <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a> 214 to 'bind' member functions: 215 </p> 216<p> 217</p> 218<pre class="programlisting"><span class="identifier">reader</span> <span class="identifier">r</span><span class="special">;</span> 219<span class="identifier">generate</span><span class="special">(</span><span class="identifier">outiter</span><span class="special">,</span> <span class="char">'{'</span> <span class="special"><<</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">reader</span><span class="special">::</span><span class="identifier">print</span><span class="special">,</span> <span class="special">&</span><span class="identifier">r</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)]</span> <span class="special"><<</span> <span class="char">'}'</span><span class="special">);</span> 220</pre> 221<p> 222 </p> 223<p> 224 Likewise, we can also use <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a> 225 to 'bind' plain functions: 226 </p> 227<p> 228</p> 229<pre class="programlisting"><span class="identifier">generate</span><span class="special">(</span><span class="identifier">outiter</span><span class="special">,</span> <span class="char">'{'</span> <span class="special"><<</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(&</span><span class="identifier">read_function</span><span class="special">,</span> <span class="identifier">_1</span><span class="special">)]</span> <span class="special"><<</span> <span class="char">'}'</span><span class="special">);</span> 230</pre> 231<p> 232 </p> 233<p> 234 And last but not least, we can also use <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a>: 235 </p> 236<p> 237</p> 238<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">strm</span><span class="special">(</span><span class="string">"42"</span><span class="special">);</span> 239<span class="identifier">generate</span><span class="special">(</span><span class="identifier">outiter</span><span class="special">,</span> <span class="char">'{'</span> <span class="special"><<</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">strm</span> <span class="special">>></span> <span class="identifier">lambda</span><span class="special">::</span><span class="identifier">_1</span><span class="special">]</span> <span class="special"><<</span> <span class="char">'}'</span><span class="special">);</span> 240</pre> 241<p> 242 </p> 243<p> 244 There are more ways to bind semantic action functions, but the examples 245 above are the most common. Attaching semantic actions is the first hurdle 246 one has to tackle when getting started with generating with Spirit. If 247 you didn't do so yet, it is probably a good idea to familiarize yourself 248 with the tools behind it such as <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a> 249 and <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a>. 250 </p> 251<p> 252 The examples above can be found here: <a href="../../../../../example/karma/actions.cpp" target="_top">actions.cpp</a> 253 </p> 254<h6> 255<a name="spirit.karma.tutorials.semantic_actions.h1"></a> 256 <span class="phrase"><a name="spirit.karma.tutorials.semantic_actions.phoenix"></a></span><a class="link" href="semantic_actions.html#spirit.karma.tutorials.semantic_actions.phoenix">Phoenix</a> 257 </h6> 258<p> 259 <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a>, 260 a companion library bundled with Spirit, is specifically suited for binding 261 semantic actions. It is like <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a> 262 on steroids, with special custom features that make it easy to integrate 263 semantic actions with Spirit. If your requirements go beyond simple to 264 moderate generation, I suggest you use this library. Examples presented 265 henceforth shall be using the Phoenix library exclusively. 266 </p> 267<div class="important"><table border="0" summary="Important"> 268<tr> 269<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../images/important.png"></td> 270<th align="left">Important</th> 271</tr> 272<tr><td align="left" valign="top"> 273<p> 274 There are different ways to write semantic actions for <span class="emphasis"><em>Spirit.Karma</em></span>: 275 using plain functions, <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a>, 276 <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a>, or 277 <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a>. 278 The latter three allow you to use special placeholders to control parameter 279 placement (<code class="computeroutput"><span class="identifier">_1</span></code>, <code class="computeroutput"><span class="identifier">_2</span></code>, etc.). Each of those libraries 280 has it's own implementation of the placeholders, all in different namespaces. 281 You have to make sure not to mix placeholders with a library they don't 282 belong to and not to use different libraries while writing a semantic 283 action. 284 </p> 285<p> 286 Generally, for <a href="../../../../../../../libs/bind/index.html" target="_top">Boost.Bind</a>, 287 use <code class="computeroutput"><span class="special">::</span><span class="identifier">_1</span></code>, 288 <code class="computeroutput"><span class="special">::</span><span class="identifier">_2</span></code>, 289 etc. (yes, these placeholders are defined in the global namespace). 290 </p> 291<p> 292 For <a href="../../../../../../../libs/lambda/index.html" target="_top">Boost.Lambda</a> use 293 the placeholders defined in the namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lambda</span></code>. 294 </p> 295<p> 296 For semantic actions written using <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a> 297 use the placeholders defined in the namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span></code>. 298 Please note that all existing placeholders for your convenience are also 299 available from the namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span></code>. 300 </p> 301</td></tr> 302</table></div> 303</div> 304<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 305<td align="left"></td> 306<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 307 Distributed under the Boost Software License, Version 1.0. (See accompanying 308 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>) 309 </p> 310</div></td> 311</tr></table> 312<hr> 313<div class="spirit-nav"> 314<a accesskey="p" href="warming_up.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="karma_complex.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 315</div> 316</body> 317</html> 318
