1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Generator Directives Consuming Attributes (omit[] and skip[])</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="../directive.html" title="Generator Directives"> 9<link rel="prev" href="buffer.html" title="Generator Directive for Temporary Output Buffering (buffer[])"> 10<link rel="next" href="duplicate.html" title="Generator Directive Duplicating Attributes (duplicate[])"> 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="buffer.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../directive.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="duplicate.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.directive.omit"></a><a class="link" href="omit.html" title="Generator Directives Consuming Attributes (omit[] and skip[])">Generator 28 Directives Consuming Attributes (<code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> and <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code>)</a> 29</h5></div></div></div> 30<h6> 31<a name="spirit.karma.reference.directive.omit.h0"></a> 32 <span class="phrase"><a name="spirit.karma.reference.directive.omit.description"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.description">Description</a> 33 </h6> 34<p> 35 The directives <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> 36 and <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code> 37 consumes the attribute type of the embedded generator without generating 38 any output. The <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> directive will still execute the embedded 39 generator while discarding the generated output afterwards. The <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code> 40 directive will not execute the embedded generator, but will use it only 41 to extract the exposed attribute type. 42 </p> 43<h6> 44<a name="spirit.karma.reference.directive.omit.h1"></a> 45 <span class="phrase"><a name="spirit.karma.reference.directive.omit.header"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.header">Header</a> 46 </h6> 47<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/directive/omit.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_omit</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<div class="informaltable"><table class="table"> 54<colgroup><col></colgroup> 55<thead><tr><th> 56 <p> 57 Name 58 </p> 59 </th></tr></thead> 60<tbody> 61<tr><td> 62 <p> 63 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">omit</span> <span class="comment">// alias: 64 boost::spirit::karma::omit</span></code> 65 </p> 66 </td></tr> 67<tr><td> 68 <p> 69 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">skip</span> <span class="comment">// alias: 70 boost::spirit::karma::skip</span></code> 71 </p> 72 </td></tr> 73</tbody> 74</table></div> 75<h6> 76<a name="spirit.karma.reference.directive.omit.h2"></a> 77 <span class="phrase"><a name="spirit.karma.reference.directive.omit.model_of"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.model_of">Model 78 of</a> 79 </h6> 80<div class="blockquote"><blockquote class="blockquote"><p> 81 <a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a> 82 </p></blockquote></div> 83<div class="variablelist"> 84<p class="title"><b>Notation</b></p> 85<dl class="variablelist"> 86<dt><span class="term"><code class="computeroutput"><span class="identifier">a</span></code></span></dt> 87<dd><p> 88 A generator object 89 </p></dd> 90<dt><span class="term"><code class="computeroutput"><span class="identifier">A</span></code></span></dt> 91<dd><p> 92 Attribute type of generator <code class="computeroutput"><span class="identifier">a</span></code> 93 </p></dd> 94</dl> 95</div> 96<h6> 97<a name="spirit.karma.reference.directive.omit.h3"></a> 98 <span class="phrase"><a name="spirit.karma.reference.directive.omit.expression_semantics"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.expression_semantics">Expression 99 Semantics</a> 100 </h6> 101<p> 102 Semantics of an expression is defined only where it differs from, or 103 is not defined in <a class="link" href="../generator_concepts/unarygenerator.html" title="UnaryGenerator"><code class="computeroutput"><span class="identifier">UnaryGenerator</span></code></a>. 104 </p> 105<div class="informaltable"><table class="table"> 106<colgroup> 107<col> 108<col> 109</colgroup> 110<thead><tr> 111<th> 112 <p> 113 Expression 114 </p> 115 </th> 116<th> 117 <p> 118 Semantics 119 </p> 120 </th> 121</tr></thead> 122<tbody> 123<tr> 124<td> 125 <p> 126 <code class="computeroutput"><span class="identifier">omit</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></code> 127 </p> 128 </td> 129<td> 130 <p> 131 The <code class="computeroutput"><span class="identifier">omit</span></code> directive 132 consumes the attribute type of the embedded generator <code class="computeroutput"><span class="identifier">A</span></code> without generating any 133 output. It succeeds always. The embedded generator is executed 134 and any generated output is discarded. 135 </p> 136 </td> 137</tr> 138<tr> 139<td> 140 <p> 141 <code class="computeroutput"><span class="identifier">skip</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></code> 142 </p> 143 </td> 144<td> 145 <p> 146 The <code class="computeroutput"><span class="identifier">skip</span></code> directive 147 consumes the attribute type of the embedded generator <code class="computeroutput"><span class="identifier">A</span></code> without generating any 148 output. It succeeds always. The embedded generator is not executed. 149 </p> 150 </td> 151</tr> 152</tbody> 153</table></div> 154<h6> 155<a name="spirit.karma.reference.directive.omit.h4"></a> 156 <span class="phrase"><a name="spirit.karma.reference.directive.omit.attributes"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.attributes">Attributes</a> 157 </h6> 158<p> 159 See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.karma.quick_reference.compound_attribute_rules.notation">Compound 160 Attribute Notation</a>. 161 </p> 162<div class="informaltable"><table class="table"> 163<colgroup> 164<col> 165<col> 166</colgroup> 167<thead><tr> 168<th> 169 <p> 170 Expression 171 </p> 172 </th> 173<th> 174 <p> 175 Attribute 176 </p> 177 </th> 178</tr></thead> 179<tbody> 180<tr> 181<td> 182 <p> 183 <code class="computeroutput"><span class="identifier">omit</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></code> 184 </p> 185 </td> 186<td> 187 <p> 188</p> 189<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--></span> <span class="identifier">omit</span><span class="special">[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">A</span> 190<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--></span> <span class="identifier">omit</span><span class="special">[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre> 191<p> 192 </p> 193 </td> 194</tr> 195<tr> 196<td> 197 <p> 198 <code class="computeroutput"><span class="identifier">skip</span><span class="special">[</span><span class="identifier">a</span><span class="special">]</span></code> 199 </p> 200 </td> 201<td> 202 <p> 203</p> 204<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--></span> <span class="identifier">skip</span><span class="special">[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">A</span> 205<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--></span> <span class="identifier">skip</span><span class="special">[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">Unused</span></pre> 206<p> 207 </p> 208 </td> 209</tr> 210</tbody> 211</table></div> 212<h6> 213<a name="spirit.karma.reference.directive.omit.h5"></a> 214 <span class="phrase"><a name="spirit.karma.reference.directive.omit.complexity"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.complexity">Complexity</a> 215 </h6> 216<div class="blockquote"><blockquote class="blockquote"><p> 217 The overall complexity of the <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> directive depends on the complexity 218 of the embedded generator. The overall complexity of the <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code> 219 generator directive is O(1) as it does not generate any output. 220 </p></blockquote></div> 221<h6> 222<a name="spirit.karma.reference.directive.omit.h6"></a> 223 <span class="phrase"><a name="spirit.karma.reference.directive.omit.example"></a></span><a class="link" href="omit.html#spirit.karma.reference.directive.omit.example">Example</a> 224 </h6> 225<div class="note"><table border="0" summary="Note"> 226<tr> 227<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 228<th align="left">Note</th> 229</tr> 230<tr><td align="left" valign="top"><p> 231 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> 232 section. 233 </p></td></tr> 234</table></div> 235<p> 236 Some includes: 237 </p> 238<p> 239</p> 240<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> 241<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> 242<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> 243<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> 244<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> 245<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 246<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 247</pre> 248<p> 249 </p> 250<p> 251 Some using declarations: 252 </p> 253<p> 254</p> 255<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">double_</span><span class="special">;</span> 256<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">omit</span><span class="special">;</span> 257</pre> 258<p> 259 </p> 260<p> 261 Basic usage of a <code class="computeroutput"><span class="identifier">omit</span></code> 262 generator directive. It shows how it consumes the first element of the 263 provided attribute without generating anything, leaving the second element 264 of the attribute to the non-wrapped <code class="computeroutput"><span class="identifier">double_</span></code> 265 generator. 266 </p> 267<p> 268</p> 269<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="keyword">double</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="identifier">p</span> <span class="special">(</span><span class="number">1.0</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span> 270<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"2.0"</span><span class="special">,</span> <span class="identifier">omit</span><span class="special">[</span><span class="identifier">double_</span><span class="special">]</span> <span class="special"><<</span> <span class="identifier">double_</span><span class="special">,</span> <span class="identifier">p</span><span class="special">);</span> 271</pre> 272<p> 273 </p> 274<p> 275 Generally, this directive is helpful in situations, where the attribute 276 type contains more information (elements) than need to be used to generate 277 the required output. Normally in such situations we would resolve to 278 use semantic actions to explicitly pass the correct parts of the overall 279 attribute to the generators. The <code class="computeroutput"><span class="identifier">omit</span></code> 280 directive helps achieving the same without having to use semantic actions. 281 </p> 282<p> 283 Consider the attribute type: 284 </p> 285<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">fusion</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="keyword">double</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">attribute_type</span><span class="special">;</span> 286</pre> 287<p> 288 where we need to generate output only from the first and last element: 289 </p> 290<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_insert</span><span class="special">:</span><span class="identifier">iterator</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">iterator_type</span><span class="special">;</span> 291 292<span class="identifier">karma</span><span class="special">::</span><span class="identifier">rule</span><span class="special"><</span><span class="identifier">iterator_type</span><span class="special">,</span> <span class="identifier">attribute_type</span><span class="special">()></span> <span class="identifier">r</span><span class="special">;</span> 293<span class="identifier">r</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">phoenix</span><span class="special">::</span><span class="identifier">at_c</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">_val</span><span class="special">)]</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">phoenix</span><span class="special">::</span><span class="identifier">at_c</span><span class="special"><</span><span class="number">2</span><span class="special">>(</span><span class="identifier">_val</span><span class="special">)];</span> 294 295<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">str</span><span class="special">;</span> 296<span class="identifier">iterator_type</span> <span class="identifier">sink</span><span class="special">(</span><span class="identifier">str</span><span class="special">);</span> 297<span class="identifier">generate</span><span class="special">(</span><span class="identifier">sink</span><span class="special">,</span> <span class="identifier">r</span><span class="special">,</span> <span class="identifier">attribute_type</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">2.0</span><span class="special">,</span> <span class="string">"example"</span><span class="special">));</span> <span class="comment">// will generate: '1example'</span> 298</pre> 299<p> 300 This is error prone and not really readable. The same can be achieved 301 by using the <code class="computeroutput"><span class="identifier">omit</span></code> directive: 302 </p> 303<pre class="programlisting"><span class="identifier">r</span> <span class="special">=</span> <span class="identifier">int_</span> <span class="special"><<</span> <span class="identifier">omit</span><span class="special">[</span><span class="identifier">double_</span><span class="special">]</span> <span class="special"><<</span> <span class="identifier">string</span><span class="special">;</span> 304</pre> 305<p> 306 which is at the same time more readable and more efficient as we don't 307 have to use semantic actions. 308 </p> 309<p> 310 The semantics of using the <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code> directive are identical to the <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> 311 directive, except that it does not actually execute the embedded generator. 312 For this reason it is usually preferable to utilize the <code class="computeroutput"><span class="identifier">skip</span><span class="special">[]</span></code> 313 directive instead of the <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> directive. On the other hand, the 314 <code class="computeroutput"><span class="identifier">omit</span><span class="special">[]</span></code> 315 directive is very useful whenever the embedded generator produces side 316 effects (has semantic actions which need to be executed). 317 </p> 318</div> 319<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 320<td align="left"></td> 321<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 322 Distributed under the Boost Software License, Version 1.0. (See accompanying 323 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>) 324 </p> 325</div></td> 326</tr></table> 327<hr> 328<div class="spirit-nav"> 329<a accesskey="p" href="buffer.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../directive.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="duplicate.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 330</div> 331</body> 332</html> 333
