1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Generator Rule</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="../nonterminal.html" title="Nonterminal Generators"> 9<link rel="prev" href="../nonterminal.html" title="Nonterminal Generators"> 10<link rel="next" href="grammar.html" title="Generator Grammar"> 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="../nonterminal.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../nonterminal.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="grammar.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h5 class="title"> 27<a name="spirit.karma.reference.nonterminal.rule"></a><a class="link" href="rule.html" title="Generator Rule">Generator 28 Rule</a> 29</h5></div></div></div> 30<h6> 31<a name="spirit.karma.reference.nonterminal.rule.h0"></a> 32 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.description"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.description">Description</a> 33 </h6> 34<p> 35 The rule is a polymorphic generator that acts as a named place-holder 36 capturing the behavior of a PEG expression assigned to it. Naming a 37 <a class="link" href="../../../abstracts/parsing_expression_grammar.html" title="Parsing Expression Grammar">Parsing Expression 38 Grammar</a> expression allows it to be referenced later and makes 39 it possible for the rule to call itself. This is one of the most important 40 mechanisms and the reason behind the word "recursive" in recursive 41 descent output generation. 42 </p> 43<h6> 44<a name="spirit.karma.reference.nonterminal.rule.h1"></a> 45 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.header"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.header">Header</a> 46 </h6> 47<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/nonterminal/rule.hpp></span> 48<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_rule</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 49</pre> 50<p> 51 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 52 </p> 53<h6> 54<a name="spirit.karma.reference.nonterminal.rule.h2"></a> 55 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.namespace"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.namespace">Namespace</a> 56 </h6> 57<div class="informaltable"><table class="table"> 58<colgroup><col></colgroup> 59<thead><tr><th> 60 <p> 61 Name 62 </p> 63 </th></tr></thead> 64<tbody><tr><td> 65 <p> 66 <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><span class="special">::</span><span class="identifier">rule</span></code> 67 </p> 68 </td></tr></tbody> 69</table></div> 70<h6> 71<a name="spirit.karma.reference.nonterminal.rule.h3"></a> 72 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.synopsis"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.synopsis">Synopsis</a> 73 </h6> 74<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> <span class="keyword">typename</span> <span class="identifier">A1</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A2</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A3</span><span class="special">></span> 75<span class="keyword">struct</span> <span class="identifier">rule</span><span class="special">;</span> 76</pre> 77<h6> 78<a name="spirit.karma.reference.nonterminal.rule.h4"></a> 79 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.template_parameters"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.template_parameters">Template 80 parameters</a> 81 </h6> 82<div class="informaltable"><table class="table"> 83<colgroup> 84<col> 85<col> 86<col> 87</colgroup> 88<thead><tr> 89<th> 90 <p> 91 Parameter 92 </p> 93 </th> 94<th> 95 <p> 96 Description 97 </p> 98 </th> 99<th> 100 <p> 101 Default 102 </p> 103 </th> 104</tr></thead> 105<tbody> 106<tr> 107<td> 108 <p> 109 <code class="computeroutput"><span class="identifier">OutputIterator</span></code> 110 </p> 111 </td> 112<td> 113 <p> 114 The underlying output iterator type that the rule is expected 115 to work on. 116 </p> 117 </td> 118<td> 119 <p> 120 none 121 </p> 122 </td> 123</tr> 124<tr> 125<td> 126 <p> 127 <code class="computeroutput"><span class="identifier">A1</span></code>, <code class="computeroutput"><span class="identifier">A2</span></code>, <code class="computeroutput"><span class="identifier">A3</span></code> 128 </p> 129 </td> 130<td> 131 <p> 132 Either <code class="computeroutput"><span class="identifier">Signature</span></code>, 133 <code class="computeroutput"><span class="identifier">Delimiter</span></code> or 134 <code class="computeroutput"><span class="identifier">Locals</span></code> in any 135 order. See table below. 136 </p> 137 </td> 138<td> 139 <p> 140 See table below. 141 </p> 142 </td> 143</tr> 144</tbody> 145</table></div> 146<p> 147 Here is more information about the template parameters: 148 </p> 149<div class="informaltable"><table class="table"> 150<colgroup> 151<col> 152<col> 153<col> 154</colgroup> 155<thead><tr> 156<th> 157 <p> 158 Parameter 159 </p> 160 </th> 161<th> 162 <p> 163 Description 164 </p> 165 </th> 166<th> 167 <p> 168 Default 169 </p> 170 </th> 171</tr></thead> 172<tbody> 173<tr> 174<td> 175 <p> 176 <code class="computeroutput"><span class="identifier">Signature</span></code> 177 </p> 178 </td> 179<td> 180 <p> 181 Specifies the rule's consumed (value to output) and inherited 182 (arguments) attributes. More on this here: <a class="link" href="../generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a>. 183 </p> 184 </td> 185<td> 186 <p> 187 <code class="computeroutput"><span class="identifier">unused_type</span></code>. 188 When <code class="computeroutput"><span class="identifier">Signature</span></code> 189 defaults to <code class="computeroutput"><span class="identifier">unused_type</span></code>, 190 the effect is the same as specifying a signature of <code class="computeroutput"><span class="keyword">void</span><span class="special">()</span></code> 191 which is also equivalent to <code class="computeroutput"><span class="identifier">unused_type</span><span class="special">()</span></code> 192 </p> 193 </td> 194</tr> 195<tr> 196<td> 197 <p> 198 <code class="computeroutput"><span class="identifier">Delimiter</span></code> 199 </p> 200 </td> 201<td> 202 <p> 203 Specifies the rule's delimiter generator. Specify this if you 204 want the rule to delimit the generated output. 205 </p> 206 </td> 207<td> 208 <p> 209 <code class="computeroutput"><span class="identifier">unused_type</span></code> 210 </p> 211 </td> 212</tr> 213<tr> 214<td> 215 <p> 216 <code class="computeroutput"><span class="identifier">Locals</span></code> 217 </p> 218 </td> 219<td> 220 <p> 221 Specifies the rule's local variables. See <a class="link" href="../generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a>. 222 </p> 223 </td> 224<td> 225 <p> 226 <code class="computeroutput"><span class="identifier">unused_type</span></code> 227 </p> 228 </td> 229</tr> 230</tbody> 231</table></div> 232<h6> 233<a name="spirit.karma.reference.nonterminal.rule.h5"></a> 234 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.model_of"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.model_of">Model of</a> 235 </h6> 236<div class="blockquote"><blockquote class="blockquote"><p> 237 <a class="link" href="../generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a> 238 </p></blockquote></div> 239<div class="variablelist"> 240<p class="title"><b>Notation</b></p> 241<dl class="variablelist"> 242<dt><span class="term"><code class="computeroutput"><span class="identifier">r</span><span class="special">,</span> 243 <span class="identifier">r2</span></code></span></dt> 244<dd><p> 245 Rules 246 </p></dd> 247<dt><span class="term"><code class="computeroutput"><span class="identifier">g</span></code></span></dt> 248<dd><p> 249 A generator expression 250 </p></dd> 251<dt><span class="term"><code class="computeroutput"><span class="identifier">OutputIterator</span></code></span></dt> 252<dd><p> 253 The underlying output iterator type that the rule is expected to 254 work on. 255 </p></dd> 256<dt><span class="term"><code class="computeroutput"><span class="identifier">A1</span></code>, <code class="computeroutput"><span class="identifier">A2</span></code>, <code class="computeroutput"><span class="identifier">A3</span></code></span></dt> 257<dd><p> 258 Either <code class="computeroutput"><span class="identifier">Signature</span></code>, 259 <code class="computeroutput"><span class="identifier">Delimiter</span></code> or <code class="computeroutput"><span class="identifier">Locals</span></code> in any order. 260 </p></dd> 261</dl> 262</div> 263<h6> 264<a name="spirit.karma.reference.nonterminal.rule.h6"></a> 265 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.expression_semantics"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.expression_semantics">Expression 266 Semantics</a> 267 </h6> 268<p> 269 Semantics of an expression is defined only where it differs from, or 270 is not defined in <a class="link" href="../generator_concepts/nonterminal.html" title="Nonterminal"><code class="computeroutput"><span class="identifier">Nonterminal</span></code></a>. 271 </p> 272<div class="informaltable"><table class="table"> 273<colgroup> 274<col> 275<col> 276</colgroup> 277<thead><tr> 278<th> 279 <p> 280 Expression 281 </p> 282 </th> 283<th> 284 <p> 285 Description 286 </p> 287 </th> 288</tr></thead> 289<tbody> 290<tr> 291<td> 292 <p> 293</p> 294<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">rule</span><span class="special"><</span><span class="identifier">OutputIterator</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">></span> 295 <span class="identifier">r</span><span class="special">(</span><span class="identifier">name</span><span class="special">);</span></pre> 296<p> 297 </p> 298 </td> 299<td> 300 <p> 301 Rule declaration. <code class="computeroutput"><span class="identifier">OutputIterator</span></code> 302 is required. <code class="computeroutput"><span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span></code> 303 are optional and can be specified in any order. <code class="computeroutput"><span class="identifier">name</span></code> is an optional string 304 that gives the rule its name, useful for debugging. 305 </p> 306 </td> 307</tr> 308<tr> 309<td> 310 <p> 311</p> 312<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">rule</span><span class="special"><</span><span class="identifier">OutputIterator</span><span class="special">,</span> <span class="identifier">A1</span><span class="special">,</span> <span class="identifier">A2</span><span class="special">,</span> <span class="identifier">A3</span><span class="special">></span> 313 <span class="identifier">r</span><span class="special">(</span><span class="identifier">r2</span><span class="special">);</span></pre> 314<p> 315 </p> 316 </td> 317<td> 318 <p> 319 Copy construct rule <code class="computeroutput"><span class="identifier">r</span></code> 320 from rule <code class="computeroutput"><span class="identifier">r2</span></code>. 321 </p> 322 </td> 323</tr> 324<tr> 325<td> 326 <p> 327 <code class="computeroutput"><span class="identifier">r</span> <span class="special">=</span> 328 <span class="identifier">r2</span><span class="special">;</span></code> 329 </p> 330 </td> 331<td> 332 <p> 333 Assign rule <code class="computeroutput"><span class="identifier">r2</span></code> 334 to <code class="computeroutput"><span class="identifier">r</span></code>. 335 </p> 336 </td> 337</tr> 338<tr> 339<td> 340 <p> 341 <code class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">alias</span><span class="special">()</span></code> 342 </p> 343 </td> 344<td> 345 <p> 346 Return an alias of <code class="computeroutput"><span class="identifier">r</span></code>. 347 The alias is a generator that holds a reference to <code class="computeroutput"><span class="identifier">r</span></code>. Reference semantics. 348 </p> 349 </td> 350</tr> 351<tr> 352<td> 353 <p> 354 <code class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">copy</span><span class="special">()</span></code> 355 </p> 356 </td> 357<td> 358 <p> 359 Get a copy of <code class="computeroutput"><span class="identifier">r</span></code>. 360 </p> 361 </td> 362</tr> 363<tr> 364<td> 365 <p> 366 <code class="computeroutput"><span class="identifier">r</span> <span class="special">=</span> 367 <span class="identifier">g</span><span class="special">;</span></code> 368 </p> 369 </td> 370<td> 371 <p> 372 Rule definition 373 </p> 374 </td> 375</tr> 376<tr> 377<td> 378 <p> 379 <code class="computeroutput"><span class="identifier">r</span> <span class="special">%=</span> 380 <span class="identifier">g</span><span class="special">;</span></code> 381 </p> 382 </td> 383<td> 384 <p> 385 Auto-rule definition. The attribute of <code class="computeroutput"><span class="identifier">g</span></code> 386 should be compatible with the consumed attribute of <code class="computeroutput"><span class="identifier">r</span></code>. 387 </p> 388 </td> 389</tr> 390<tr> 391<td> 392 <p> 393 <code class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></code> 394 </p> 395 </td> 396<td> 397 <p> 398 Retrieve the current name of the rule object. 399 </p> 400 </td> 401</tr> 402<tr> 403<td> 404 <p> 405 <code class="computeroutput"><span class="identifier">r</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code> 406 </p> 407 </td> 408<td> 409 <p> 410 Set the current name of the rule object to be <code class="computeroutput"><span class="identifier">name</span></code>. 411 </p> 412 </td> 413</tr> 414</tbody> 415</table></div> 416<h6> 417<a name="spirit.karma.reference.nonterminal.rule.h7"></a> 418 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.attributes"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.attributes">Attributes</a> 419 </h6> 420<div class="blockquote"><blockquote class="blockquote"><p> 421 The rule's generator attribute is <code class="computeroutput"><span class="identifier">RT</span></code>: 422 The consumed attribute of the rule. See <a class="link" href="../generator_concepts/nonterminal.html#spirit.karma.reference.generator_concepts.nonterminal.attributes"><code class="computeroutput"><span class="identifier">Attribute</span></code></a> 423 </p></blockquote></div> 424<h6> 425<a name="spirit.karma.reference.nonterminal.rule.h8"></a> 426 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.complexity"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.complexity">Complexity</a> 427 </h6> 428<div class="blockquote"><blockquote class="blockquote"><p> 429 The complexity is defined by the complexity of the RHS generator, 430 <code class="computeroutput"><span class="identifier">g</span></code> 431 </p></blockquote></div> 432<h6> 433<a name="spirit.karma.reference.nonterminal.rule.h9"></a> 434 <span class="phrase"><a name="spirit.karma.reference.nonterminal.rule.example"></a></span><a class="link" href="rule.html#spirit.karma.reference.nonterminal.rule.example">Example</a> 435 </h6> 436<div class="note"><table border="0" summary="Note"> 437<tr> 438<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 439<th align="left">Note</th> 440</tr> 441<tr><td align="left" valign="top"><p> 442 The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.karma.reference.basics.examples">Basics Examples</a> 443 section. 444 </p></td></tr> 445</table></div> 446<p> 447 Some using declarations: 448 </p> 449<p> 450</p> 451<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">rule</span><span class="special">;</span> 452<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> 453<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">ascii</span><span class="special">::</span><span class="identifier">space</span><span class="special">;</span> 454<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">ascii</span><span class="special">::</span><span class="identifier">space_type</span><span class="special">;</span> 455</pre> 456<p> 457 </p> 458<p> 459 Basic rule: 460 </p> 461<p> 462</p> 463<pre class="programlisting"><span class="identifier">rule</span><span class="special"><</span><span class="identifier">output_iterator_type</span><span class="special">></span> <span class="identifier">r</span><span class="special">;</span> 464<span class="identifier">r</span> <span class="special">=</span> <span class="identifier">int_</span><span class="special">(</span><span class="number">123</span><span class="special">);</span> 465<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"123"</span><span class="special">,</span> <span class="identifier">r</span><span class="special">);</span> 466</pre> 467<p> 468 </p> 469<p> 470 Rule with consumed attribute: 471 </p> 472<p> 473</p> 474<pre class="programlisting"><span class="identifier">rule</span><span class="special"><</span><span class="identifier">output_iterator_type</span><span class="special">,</span> <span class="keyword">int</span><span class="special">()></span> <span class="identifier">ra</span><span class="special">;</span> 475<span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">int_</span><span class="special">;</span> 476<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"123"</span><span class="special">,</span> <span class="identifier">ra</span><span class="special">,</span> <span class="number">123</span><span class="special">);</span> 477</pre> 478<p> 479 </p> 480<p> 481 Rule with delimiter and consumed attribute: 482 </p> 483<p> 484</p> 485<pre class="programlisting"><span class="identifier">rule</span><span class="special"><</span><span class="identifier">output_iterator_type</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(),</span> <span class="identifier">space_type</span><span class="special">></span> <span class="identifier">rs</span><span class="special">;</span> 486<span class="identifier">rs</span> <span class="special">=</span> <span class="special">*</span><span class="identifier">int_</span><span class="special">;</span> 487<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> 488<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">123</span><span class="special">);</span> 489<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">456</span><span class="special">);</span> 490<span class="identifier">v</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">789</span><span class="special">);</span> 491<span class="identifier">test_generator_attr_delim</span><span class="special">(</span><span class="string">"123 456 789"</span><span class="special">,</span> <span class="identifier">rs</span><span class="special">,</span> <span class="identifier">space</span><span class="special">,</span> <span class="identifier">v</span><span class="special">);</span> 492</pre> 493<p> 494 </p> 495</div> 496<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 497<td align="left"></td> 498<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 499 Distributed under the Boost Software License, Version 1.0. (See accompanying 500 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>) 501 </p> 502</div></td> 503</tr></table> 504<hr> 505<div class="spirit-nav"> 506<a accesskey="p" href="../nonterminal.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../nonterminal.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="grammar.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 507</div> 508</body> 509</html> 510
