1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Alternative Parser (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="Parser Operators"> 9<link rel="prev" href="../operator.html" title="Parser Operators"> 10<link rel="next" href="and_predicate.html" title="And-Predicate Parser (&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="../operator.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="and_predicate.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.qi.reference.operator.alternative"></a><a class="link" href="alternative.html" title="Alternative Parser (a | b)">Alternative 28 Parser (<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.qi.reference.operator.alternative.h0"></a> 33 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.description"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.description">Description</a> 34 </h6> 35<p> 36 The alternative operator, <code class="computeroutput"><span class="identifier">a</span> 37 <span class="special">|</span> <span class="identifier">b</span></code>, 38 matches one of two or more operands (<code class="computeroutput"><span class="identifier">a</span></code>, 39 <code class="computeroutput"><span class="identifier">b</span></code>, ... etc.): 40 </p> 41<pre class="programlisting"><span class="identifier">a</span> <span class="special">|</span> <span class="identifier">b</span> <span class="special">|</span> <span class="special">...</span> 42</pre> 43<p> 44 Alternative operands are tried one by one on a first-match-wins basis 45 starting from the leftmost operand. After a successfully matched alternative 46 is found, the parser concludes its search, essentially short-circuiting 47 the search for other potentially viable candidates. This short-circuiting 48 implicitly gives the highest priority to the leftmost alternative. 49 </p> 50<p> 51 Short-circuiting is done in the same manner as C or C++'s logical expressions; 52 e.g. <code class="computeroutput"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">x</span> <span class="special"><</span> <span class="number">3</span> <span class="special">||</span> <span class="identifier">y</span> 53 <span class="special"><</span> <span class="number">2</span><span class="special">)</span></code> where, if <code class="computeroutput"><span class="identifier">x</span> 54 <span class="special"><</span> <span class="number">3</span></code>, 55 the <code class="computeroutput"><span class="identifier">y</span> <span class="special"><</span> 56 <span class="number">2</span></code> test is not done at all. In addition 57 to providing an implicit priority rule for alternatives which is necessary, 58 given its non-deterministic nature, short-circuiting improves the execution 59 time. If the order of your alternatives is logically irrelevant, strive 60 to put the (expected) most common choice first for maximum efficiency. 61 </p> 62<h6> 63<a name="spirit.qi.reference.operator.alternative.h1"></a> 64 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.header"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.header">Header</a> 65 </h6> 66<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/qi/operator/alternative.hpp></span> 67<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">qi_alternative</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 68</pre> 69<p> 70 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 71 </p> 72<h6> 73<a name="spirit.qi.reference.operator.alternative.h2"></a> 74 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.model_of"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.model_of">Model of</a> 75 </h6> 76<div class="blockquote"><blockquote class="blockquote"><p> 77 <a class="link" href="../parser_concepts/naryparser.html" title="NaryParser"><code class="computeroutput"><span class="identifier">NaryParser</span></code></a> 78 </p></blockquote></div> 79<div class="variablelist"> 80<p class="title"><b>Notation</b></p> 81<dl class="variablelist"> 82<dt><span class="term"><code class="computeroutput"><span class="identifier">a</span></code>, <code class="computeroutput"><span class="identifier">b</span></code></span></dt> 83<dd><p> 84 A <a class="link" href="../parser_concepts/parser.html" title="Parser"><code class="computeroutput"><span class="identifier">Parser</span></code></a> 85 </p></dd> 86</dl> 87</div> 88<h6> 89<a name="spirit.qi.reference.operator.alternative.h3"></a> 90 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.expression_semantics"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.expression_semantics">Expression 91 Semantics</a> 92 </h6> 93<p> 94 Semantics of an expression is defined only where it differs from, or 95 is not defined in <a class="link" href="../parser_concepts/naryparser.html" title="NaryParser"><code class="computeroutput"><span class="identifier">NaryParser</span></code></a>. 96 </p> 97<div class="informaltable"><table class="table"> 98<colgroup> 99<col> 100<col> 101</colgroup> 102<thead><tr> 103<th> 104 <p> 105 Expression 106 </p> 107 </th> 108<th> 109 <p> 110 Semantics 111 </p> 112 </th> 113</tr></thead> 114<tbody><tr> 115<td> 116 <p> 117 <code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span> 118 <span class="identifier">b</span></code> 119 </p> 120 </td> 121<td> 122 <p> 123 Match <code class="computeroutput"><span class="identifier">a</span></code> or 124 <code class="computeroutput"><span class="identifier">b</span></code>. 125 </p> 126 </td> 127</tr></tbody> 128</table></div> 129<h6> 130<a name="spirit.qi.reference.operator.alternative.h4"></a> 131 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.attributes"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.attributes">Attributes</a> 132 </h6> 133<p> 134 See <a class="link" href="../../quick_reference/compound_attribute_rules.html#spirit.qi.quick_reference.compound_attribute_rules.notation">Compound 135 Attribute Notation</a>. 136 </p> 137<div class="informaltable"><table class="table"> 138<colgroup> 139<col> 140<col> 141</colgroup> 142<thead><tr> 143<th> 144 <p> 145 Expression 146 </p> 147 </th> 148<th> 149 <p> 150 Attribute 151 </p> 152 </th> 153</tr></thead> 154<tbody><tr> 155<td> 156 <p> 157 <code class="computeroutput"><span class="identifier">a</span> <span class="special">|</span> 158 <span class="identifier">b</span></code> 159 </p> 160 </td> 161<td> 162 <p> 163</p> 164<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> 165<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">optional</span><span class="special"><</span><span class="identifier">A</span><span class="special">></span> 166<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="identifier">c</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">c</span><span class="special">):</span> <span class="identifier">optional</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> <span class="special">></span> 167<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">optional</span><span class="special"><</span><span class="identifier">B</span><span class="special">></span> 168<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> 169<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> 170<p> 171 </p> 172 </td> 173</tr></tbody> 174</table></div> 175<div class="note"><table border="0" summary="Note"> 176<tr> 177<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 178<th align="left">Note</th> 179</tr> 180<tr><td align="left" valign="top"><p> 181 Alternative parsers do not roll back changes made to the outer attribute 182 because of a failed alternative. If you need to enforce that only the 183 succeeded alternative changes the outer attribute please utilize the 184 directive <a class="link" href="../directive/hold.html" title="Parser Directive for Attribute Commit/Rollback (hold[])"><code class="computeroutput"><span class="identifier">hold</span></code></a><code class="computeroutput"><span class="special">[]</span></code>. 185 </p></td></tr> 186</table></div> 187<h6> 188<a name="spirit.qi.reference.operator.alternative.h5"></a> 189 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.complexity"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.complexity">Complexity</a> 190 </h6> 191<div class="blockquote"><blockquote class="blockquote"><p> 192 The overall complexity of the alternative parser is defined by the 193 sum of the complexities of its elements. The complexity of the alternative 194 parser itself is O(N), where N is the number of alternatives. 195 </p></blockquote></div> 196<h6> 197<a name="spirit.qi.reference.operator.alternative.h6"></a> 198 <span class="phrase"><a name="spirit.qi.reference.operator.alternative.example"></a></span><a class="link" href="alternative.html#spirit.qi.reference.operator.alternative.example">Example</a> 199 </h6> 200<div class="note"><table border="0" summary="Note"> 201<tr> 202<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 203<th align="left">Note</th> 204</tr> 205<tr><td align="left" valign="top"><p> 206 The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.qi.reference.basics.examples">Basics Examples</a> 207 section. 208 </p></td></tr> 209</table></div> 210<p> 211 Some using declarations: 212 </p> 213<p> 214</p> 215<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">ascii</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span> 216<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">qi</span><span class="special">::</span><span class="identifier">int_</span><span class="special">;</span> 217<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">qi</span><span class="special">::</span><span class="identifier">_1</span><span class="special">;</span> 218<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special">;</span> 219</pre> 220<p> 221 </p> 222<p> 223 Simple usage: 224 </p> 225<p> 226</p> 227<pre class="programlisting"><span class="identifier">test_parser</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">,</span> <span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">)</span> <span class="special">|</span> <span class="identifier">int_</span><span class="special">);</span> 228<span class="identifier">test_parser</span><span class="special">(</span><span class="string">"123"</span><span class="special">,</span> <span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">)</span> <span class="special">|</span> <span class="identifier">int_</span><span class="special">);</span> 229</pre> 230<p> 231 </p> 232<p> 233 Extracting the attribute variant (using <a href="http://www.boost.org/doc/html/variant.html" target="_top">Boost.Variant</a>): 234 </p> 235<p> 236</p> 237<pre class="programlisting"><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">int</span><span class="special">></span> <span class="identifier">attr</span><span class="special">;</span> 238<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">,</span> <span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">)</span> <span class="special">|</span> <span class="identifier">int_</span><span class="special">,</span> <span class="identifier">attr</span><span class="special">);</span> 239</pre> 240<p> 241 </p> 242<p> 243 This should print <code class="computeroutput"><span class="string">"Hello"</span></code>. 244 Note: There are better ways to extract the value from the variant. See 245 <a href="http://www.boost.org/doc/html/variant.html" target="_top">Boost.Variant</a> 246 visitation. This code is solely for demonstration. 247 </p> 248<p> 249</p> 250<pre class="programlisting"><span class="keyword">if</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">get</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(&</span><span class="identifier">attr</span><span class="special">))</span> 251 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">get</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">attr</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 252<span class="keyword">else</span> 253 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">get</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">attr</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 254</pre> 255<p> 256 </p> 257<p> 258 Extracting the attributes using Semantic Actions with <a href="../../../../../../../../libs/phoenix/doc/html/index.html" target="_top">Boost.Phoenix</a> 259 (this should print <code class="computeroutput"><span class="number">123</span></code>): 260 </p> 261<p> 262</p> 263<pre class="programlisting"><span class="identifier">test_parser</span><span class="special">(</span><span class="string">"123"</span><span class="special">,</span> <span class="special">(</span><span class="identifier">string</span><span class="special">(</span><span class="string">"Hello"</span><span class="special">)</span> <span class="special">|</span> <span class="identifier">int_</span><span class="special">)[</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">_1</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">]);</span> 264</pre> 265<p> 266 </p> 267</div> 268<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 269<td align="left"></td> 270<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 271 Distributed under the Boost Software License, Version 1.0. (See accompanying 272 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>) 273 </p> 274</div></td> 275</tr></table> 276<hr> 277<div class="spirit-nav"> 278<a accesskey="p" href="../operator.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="and_predicate.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 279</div> 280</body> 281</html> 282
