1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Alternative Generator (a | b)</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="../operator.html" title="Generator Operators"> 9<link rel="prev" href="sequence.html" title="Sequence Generator (a << b)"> 10<link rel="next" href="kleene.html" title="Kleene Star Generator (*a)"> 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="sequence.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.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="kleene.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.operator.alternative"></a><a class="link" href="alternative.html" title="Alternative Generator (a | b)">Alternative 28 Generator (<code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span> 29 <span class="identifier">b</span></code>)</a> 30</h5></div></div></div> 31<h6> 32<a name="spirit.karma.reference.operator.alternative.h0"></a> 33 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.description"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.description">Description</a> 34 </h6> 35<p> 36 Generator alternatives are used to combine different, more primitive 37 generators into alternatives. All generators in an alternative are invoked 38 from left to right until one of them succeeds. 39 </p> 40<h6> 41<a name="spirit.karma.reference.operator.alternative.h1"></a> 42 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.header"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.header">Header</a> 43 </h6> 44<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/operator/alternative.hpp></span> 45<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_alternative</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 46</pre> 47<p> 48 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 49 </p> 50<h6> 51<a name="spirit.karma.reference.operator.alternative.h2"></a> 52 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.model_of"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.model_of">Model 53 of</a> 54 </h6> 55<div class="blockquote"><blockquote class="blockquote"><p> 56 <a class="link" href="../generator_concepts/narygenerator.html" title="NaryGenerator"><code class="computeroutput"><span class="identifier">NaryGenerator</span></code></a> 57 </p></blockquote></div> 58<h6> 59<a name="spirit.karma.reference.operator.alternative.h3"></a> 60 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.expression_semantics"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.expression_semantics">Expression 61 Semantics</a> 62 </h6> 63<p> 64 Semantics of an expression is defined only where it differs from, or 65 is not defined in <a class="link" href="../generator_concepts/narygenerator.html" title="NaryGenerator"><code class="computeroutput"><span class="identifier">NaryGenerator</span></code></a>. 66 </p> 67<div class="informaltable"><table class="table"> 68<colgroup> 69<col> 70<col> 71</colgroup> 72<thead><tr> 73<th> 74 <p> 75 Expression 76 </p> 77 </th> 78<th> 79 <p> 80 Semantics 81 </p> 82 </th> 83</tr></thead> 84<tbody><tr> 85<td> 86 <p> 87 <code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span> 88 <span class="identifier">b</span></code> 89 </p> 90 </td> 91<td> 92 <p> 93 The generators <code class="computeroutput"><span class="identifier">a</span></code> 94 and <code class="computeroutput"><span class="identifier">b</span></code> are executed 95 sequentially from left to right until one of them succeeds. 96 A failed generator forces the alternative generator to try 97 the next one. The alternative fails as a whole only if all 98 elements of the alternative fail. Each element of the alternative 99 gets passed the whole attribute of the alternative. 100 </p> 101 </td> 102</tr></tbody> 103</table></div> 104<p> 105 Alternatives intercept and buffer the output of the currently executed 106 element. This allows to avoid partial outputs from failing elements as 107 the buffered content will be forwarded to the actual output only after 108 an element succeeded. 109 </p> 110<h6> 111<a name="spirit.karma.reference.operator.alternative.h4"></a> 112 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.attributes"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.attributes">Attributes</a> 113 </h6> 114<p> 115 See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.karma.quick_reference.compound_attribute_rules.notation">Compound 116 Attribute Notation</a>. 117 </p> 118<div class="informaltable"><table class="table"> 119<colgroup> 120<col> 121<col> 122</colgroup> 123<thead><tr> 124<th> 125 <p> 126 Expression 127 </p> 128 </th> 129<th> 130 <p> 131 Attribute 132 </p> 133 </th> 134</tr></thead> 135<tbody><tr> 136<td> 137 <p> 138 <code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span> 139 <span class="identifier">b</span></code> (alternative) 140 </p> 141 </td> 142<td> 143 <p> 144</p> 145<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">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--></span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span> 146<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--></span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span> 147<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">B</span> <span class="special">--></span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">B</span> 148<span class="identifier">a</span><span class="special">:</span> <span class="identifier">Unused</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">Unused</span> <span class="special">--></span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">Unused</span> 149<span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span><span class="special">,</span> <span class="identifier">b</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--></span> <span class="special">(</span><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span><span class="special">):</span> <span class="identifier">A</span></pre> 150<p> 151 </p> 152 </td> 153</tr></tbody> 154</table></div> 155<div class="important"><table border="0" summary="Important"> 156<tr> 157<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../images/important.png"></td> 158<th align="left">Important</th> 159</tr> 160<tr><td align="left" valign="top"><p> 161 The table above uses <code class="computeroutput"><span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code> as a placeholder only. The notation 162 <code class="computeroutput"><span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code> 163 stands for the type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">></span></code>. 164 </p></td></tr> 165</table></div> 166<p> 167 The attribute handling of Alternatives is special as their behavior is 168 not completely defined at compile time. First of all the selected alternative 169 element depends on the actual type of the attribute supplied to the alternative 170 generator (i.e. what is stored in the variant). The attribute type supplied 171 at <span class="emphasis"><em>runtime</em></span> narrows the set of considered alternatives 172 to those being compatible attribute wise. The remaining alternatives 173 are tried sequentially until the first of them succeeds. See below for 174 an example of this behavior. 175 </p> 176<h6> 177<a name="spirit.karma.reference.operator.alternative.h5"></a> 178 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.complexity"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.complexity">Complexity</a> 179 </h6> 180<div class="blockquote"><blockquote class="blockquote"><p> 181 The overall complexity of the alternative generator is defined by the 182 sum of the complexities of its elements. The complexity of the alternative 183 itself is O(N), where N is the number of elements in the alternative. 184 </p></blockquote></div> 185<h6> 186<a name="spirit.karma.reference.operator.alternative.h6"></a> 187 <span class="phrase"><a name="spirit.karma.reference.operator.alternative.example"></a></span><a class="link" href="alternative.html#spirit.karma.reference.operator.alternative.example">Example</a> 188 </h6> 189<div class="note"><table border="0" summary="Note"> 190<tr> 191<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 192<th align="left">Note</th> 193</tr> 194<tr><td align="left" valign="top"><p> 195 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> 196 section. 197 </p></td></tr> 198</table></div> 199<p> 200 Some includes: 201 </p> 202<p> 203</p> 204<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> 205<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> 206<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> 207<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> 208<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> 209<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 210<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 211</pre> 212<p> 213 </p> 214<p> 215 Some using declarations: 216 </p> 217<p> 218</p> 219<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> 220<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">ascii</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span> 221</pre> 222<p> 223 </p> 224<p> 225 Basic usage of an alternative. While being only the second alternative, 226 the <code class="computeroutput"><span class="identifier">double_</span></code> generator 227 is chosen for output formatting because the supplied attribute type is 228 not compatible (i.e. not convertible) to the attribute type of the <code class="computeroutput"><span class="identifier">string</span></code> alternative. 229 </p> 230<p> 231</p> 232<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</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="keyword">double</span><span class="special">></span> <span class="identifier">v1</span><span class="special">(</span><span class="number">1.0</span><span class="special">);</span> 233<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"1.0"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="identifier">v1</span><span class="special">);</span> 234<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"2.0"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span> 235</pre> 236<p> 237 </p> 238<p> 239 The same formatting rules may be used to output a string. This time we 240 supply the string <code class="computeroutput"><span class="string">"example"</span></code>, 241 resulting in the first alternative to be chosen for the generated output. 242 </p> 243<p> 244</p> 245<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</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="keyword">double</span><span class="special">></span> <span class="identifier">v2</span><span class="special">(</span><span class="string">"example"</span><span class="special">);</span> 246<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"example"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="identifier">v2</span><span class="special">);</span> 247<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"example"</span><span class="special">,</span> <span class="identifier">string</span> <span class="special">|</span> <span class="identifier">double_</span><span class="special">,</span> <span class="string">"example"</span><span class="special">);</span> 248</pre> 249<p> 250 </p> 251</div> 252<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 253<td align="left"></td> 254<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 255 Distributed under the Boost Software License, Version 1.0. (See accompanying 256 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>) 257 </p> 258</div></td> 259</tr></table> 260<hr> 261<div class="spirit-nav"> 262<a accesskey="p" href="sequence.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../operator.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="kleene.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 263</div> 264</body> 265</html> 266
