1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Semantic Actions with Generators</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="../reference.html" title="Reference"> 9<link rel="prev" href="generate_api/create_generator.html" title="API for Automatic Generator Creation"> 10<link rel="next" href="auto.html" title="Auto 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="generate_api/create_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="auto.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.reference.action"></a><a class="link" href="action.html" title="Semantic Actions with Generators">Semantic Actions with 28 Generators</a> 29</h4></div></div></div> 30<h6> 31<a name="spirit.karma.reference.action.h0"></a> 32 <span class="phrase"><a name="spirit.karma.reference.action.description"></a></span><a class="link" href="action.html#spirit.karma.reference.action.description">Description</a> 33 </h6> 34<p> 35 Semantic actions may be attached to any point in the grammar specification. 36 They allow to call a function or function object in order to provide the 37 value output by the generator attached to the semantic action. Semantic 38 actions are associated with a generator using the syntax <code class="computeroutput"><span class="identifier">g</span><span class="special">[]</span></code>, 39 where <code class="computeroutput"><span class="identifier">g</span></code> is an arbitrary 40 generator expression. 41 </p> 42<h6> 43<a name="spirit.karma.reference.action.h1"></a> 44 <span class="phrase"><a name="spirit.karma.reference.action.header"></a></span><a class="link" href="action.html#spirit.karma.reference.action.header">Header</a> 45 </h6> 46<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/action.hpp></span> 47<span class="preprocessor">#include</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">include</span><span class="special">/</span><span class="identifier">karma_action</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 48</pre> 49<p> 50 Also, see <a class="link" href="../../structure/include.html" title="Include">Include Structure</a>. 51 </p> 52<h6> 53<a name="spirit.karma.reference.action.h2"></a> 54 <span class="phrase"><a name="spirit.karma.reference.action.model_of"></a></span><a class="link" href="action.html#spirit.karma.reference.action.model_of">Model 55 of</a> 56 </h6> 57<div class="blockquote"><blockquote class="blockquote"><p> 58 <a class="link" href="generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a> 59 </p></blockquote></div> 60<div class="variablelist"> 61<p class="title"><b>Notation</b></p> 62<dl class="variablelist"> 63<dt><span class="term"><code class="computeroutput"><span class="identifier">a</span></code>, <code class="computeroutput"><span class="identifier">g</span></code></span></dt> 64<dd><p> 65 Instances of a generator, <code class="computeroutput"><span class="identifier">G</span></code> 66 </p></dd> 67<dt><span class="term"><code class="computeroutput"><span class="identifier">A</span></code></span></dt> 68<dd><p> 69 Attribute type exposed by a generator, <code class="computeroutput"><span class="identifier">a</span></code> 70 </p></dd> 71<dt><span class="term"><code class="computeroutput"><span class="identifier">fa</span></code></span></dt> 72<dd><p> 73 A (semantic action) function with signature <code class="computeroutput"><span class="keyword">void</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></code>. The third parameter is a boolean 74 flag that can be set to false to force the generator to fail. Both 75 <code class="computeroutput"><span class="identifier">Context</span></code> and the boolean 76 flag are optional. For more information see below. 77 </p></dd> 78<dt><span class="term"><code class="computeroutput"><span class="identifier">Attrib</span></code></span></dt> 79<dd><p> 80 The attribute to be used to generate output from. 81 </p></dd> 82<dt><span class="term"><code class="computeroutput"><span class="identifier">Context</span></code></span></dt> 83<dd><p> 84 The type of the generator execution context. For more information 85 see below. 86 </p></dd> 87</dl> 88</div> 89<h6> 90<a name="spirit.karma.reference.action.h3"></a> 91 <span class="phrase"><a name="spirit.karma.reference.action.expression_semantics"></a></span><a class="link" href="action.html#spirit.karma.reference.action.expression_semantics">Expression 92 Semantics</a> 93 </h6> 94<p> 95 Semantics of an expression is defined only where it differs from, or is 96 not defined in <a class="link" href="generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>. 97 </p> 98<div class="informaltable"><table class="table"> 99<colgroup> 100<col> 101<col> 102</colgroup> 103<thead><tr> 104<th> 105 <p> 106 Expression 107 </p> 108 </th> 109<th> 110 <p> 111 Semantics 112 </p> 113 </th> 114</tr></thead> 115<tbody><tr> 116<td> 117 <p> 118 <code class="computeroutput"><span class="identifier">g</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]</span></code> 119 </p> 120 </td> 121<td> 122 <p> 123 Call semantic action, <code class="computeroutput"><span class="identifier">fa</span></code> 124 <span class="emphasis"><em>before</em></span> invoking <code class="computeroutput"><span class="identifier">g</span></code>. 125 The function or function object <code class="computeroutput"><span class="identifier">fa</span></code> 126 is expected to provide the value to generate output from to the 127 generator <code class="computeroutput"><span class="identifier">g</span></code>. 128 </p> 129 </td> 130</tr></tbody> 131</table></div> 132<p> 133 The possible signatures for functions to be used as semantic actions are: 134 </p> 135<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">></span> 136<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">);</span> 137 138<span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Context</span><span class="special">></span> 139<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">&</span> <span class="identifier">context</span><span class="special">);</span> 140 141<span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Context</span><span class="special">></span> 142<span class="keyword">void</span> <span class="identifier">fa</span><span class="special">(</span><span class="identifier">Attrib</span><span class="special">&</span> <span class="identifier">attr</span><span class="special">,</span> <span class="identifier">Context</span><span class="special">&</span> <span class="identifier">context</span><span class="special">,</span> <span class="keyword">bool</span><span class="special">&</span> <span class="identifier">pass</span><span class="special">);</span> 143</pre> 144<p> 145 The function or function object is expected to return the value to generate 146 output from by assigning it to the first parameter, <code class="computeroutput"><span class="identifier">attr</span></code>. 147 Here <code class="computeroutput"><span class="identifier">Attrib</span></code> is the attribute 148 type of the generator attached to the semantic action. 149 </p> 150<p> 151 The type <code class="computeroutput"><span class="identifier">Context</span></code> is the 152 type of the generator execution context. This type is unspecified and depends 153 on the context the generator is invoked in. The value <code class="computeroutput"><span class="identifier">context</span></code> 154 is used by semantic actions written using <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a> 155 to access various context dependent attributes and values. For more information 156 about <a href="../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a> 157 placeholder expressions usable in semantic actions see <a class="link" href="generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a>. 158 </p> 159<p> 160 The third parameter, <code class="computeroutput"><span class="identifier">pass</span></code>, 161 can be used by the semantic action to force the associated generator to 162 fail. If pass is set to <code class="computeroutput"><span class="keyword">false</span></code> 163 the action generator will immediately return <code class="computeroutput"><span class="keyword">false</span></code> 164 as well, while not invoking <code class="computeroutput"><span class="identifier">g</span></code> 165 and not generating any output. 166 </p> 167<h6> 168<a name="spirit.karma.reference.action.h4"></a> 169 <span class="phrase"><a name="spirit.karma.reference.action.attributes"></a></span><a class="link" href="action.html#spirit.karma.reference.action.attributes">Attributes</a> 170 </h6> 171<div class="informaltable"><table class="table"> 172<colgroup> 173<col> 174<col> 175</colgroup> 176<thead><tr> 177<th> 178 <p> 179 Expression 180 </p> 181 </th> 182<th> 183 <p> 184 Attribute 185 </p> 186 </th> 187</tr></thead> 188<tbody><tr> 189<td> 190 <p> 191 <code class="computeroutput"><span class="identifier">a</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]</span></code> 192 </p> 193 </td> 194<td> 195 <p> 196 <code class="computeroutput"><span class="identifier">a</span><span class="special">:</span> 197 <span class="identifier">A</span> <span class="special">--></span> 198 <span class="identifier">a</span><span class="special">[</span><span class="identifier">fa</span><span class="special">]:</span> 199 <span class="identifier">A</span></code> 200 </p> 201 </td> 202</tr></tbody> 203</table></div> 204<h6> 205<a name="spirit.karma.reference.action.h5"></a> 206 <span class="phrase"><a name="spirit.karma.reference.action.complexity"></a></span><a class="link" href="action.html#spirit.karma.reference.action.complexity">Complexity</a> 207 </h6> 208<p> 209 The complexity of the action generator is defined by the complexity of 210 the generator the semantic action is attached to and the complexity of 211 the function or function object used as the semantic action. 212 </p> 213<div class="important"><table border="0" summary="Important"> 214<tr> 215<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../images/important.png"></td> 216<th align="left">Important</th> 217</tr> 218<tr><td align="left" valign="top"><p> 219 Please note that the use of semantic actions in <span class="emphasis"><em>Spirit.Karma</em></span> 220 generally forces the library to create a <span class="emphasis"><em>copy</em></span> of 221 the attribute, which might be a costly operation. Always consider using 222 other means of associating a value with a particular generator first. 223 </p></td></tr> 224</table></div> 225<h6> 226<a name="spirit.karma.reference.action.h6"></a> 227 <span class="phrase"><a name="spirit.karma.reference.action.example"></a></span><a class="link" href="action.html#spirit.karma.reference.action.example">Example</a> 228 </h6> 229<div class="note"><table border="0" summary="Note"> 230<tr> 231<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../images/note.png"></td> 232<th align="left">Note</th> 233</tr> 234<tr><td align="left" valign="top"><p> 235 The test harness for the example(s) below is presented in the <a class="link" href="basics.html#spirit.karma.reference.basics.examples">Basics 236 Examples</a> section. 237 </p></td></tr> 238</table></div> 239<p> 240 Some includes: 241 </p> 242<p> 243</p> 244<pre class="programlisting"><span class="preprocessor">#include</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">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 245<span class="preprocessor">#include</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">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 246<span class="preprocessor">#include</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">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 247<span class="preprocessor">#include</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">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 248<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 249<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 250<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 251</pre> 252<p> 253 </p> 254<p> 255 Some using declarations: 256 </p> 257<p> 258</p> 259<pre class="programlisting"><span class="keyword">using</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><span class="identifier">int_</span><span class="special">;</span> 260<span class="keyword">using</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><span class="identifier">string</span><span class="special">;</span> 261<span class="keyword">using</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><span class="identifier">_1</span><span class="special">;</span> 262<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">ref</span><span class="special">;</span> 263<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">::</span><span class="identifier">val</span><span class="special">;</span> 264</pre> 265<p> 266 </p> 267<p> 268 Some examples: 269 </p> 270<p> 271</p> 272<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">42</span><span class="special">;</span> 273<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"42"</span><span class="special">,</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">_1</span> <span class="special">=</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">i</span><span class="special">)]);</span> 274<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"abc"</span><span class="special">,</span> <span class="identifier">string</span><span class="special">[</span><span class="identifier">_1</span> <span class="special">=</span> <span class="identifier">val</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)]);</span> 275</pre> 276<p> 277 </p> 278<p> 279 More examples for semantic actions can be found here: <a class="link" href="../tutorials/semantic_actions.html#spirit.karma.tutorials.semantic_actions.examples_of_semantic_actions">Examples 280 of Semantic Actions</a>. 281 </p> 282</div> 283<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 284<td align="left"></td> 285<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 286 Distributed under the Boost Software License, Version 1.0. (See accompanying 287 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>) 288 </p> 289</div></td> 290</tr></table> 291<hr> 292<div class="spirit-nav"> 293<a accesskey="p" href="generate_api/create_generator.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.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="auto.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a> 294</div> 295</body> 296</html> 297
