1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Epsilon Generator (eps)</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="../auxiliary.html" title="Auxiliary Generators"> 9<link rel="prev" href="eol.html" title="End of Line Generator (eol)"> 10<link rel="next" href="lazy.html" title="Lazy Generator (lazy)"> 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="eol.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../auxiliary.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="lazy.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.auxiliary.eps"></a><a class="link" href="eps.html" title="Epsilon Generator (eps)">Epsilon Generator 28 (<code class="computeroutput"><span class="identifier">eps</span></code>)</a> 29</h5></div></div></div> 30<p> 31 The family of <code class="computeroutput"><span class="identifier">eps</span></code> components 32 allows to create pseudo generators generating an empty string. This feature 33 is sometimes useful either to force a generator to fail or to succeed 34 or to insert semantic actions into the generation process. 35 </p> 36<h6> 37<a name="spirit.karma.reference.auxiliary.eps.h0"></a> 38 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.description"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.description">Description</a> 39 </h6> 40<p> 41 The Epsilon (<code class="computeroutput"><span class="identifier">eps</span></code>) is 42 a multi-purpose generator that emits a zero length string. 43 </p> 44<h6> 45<a name="spirit.karma.reference.auxiliary.eps.h1"></a> 46 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.simple_form"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.simple_form">Simple Form</a> 47 </h6> 48<p> 49 In its simplest form, <code class="computeroutput"><span class="identifier">eps</span></code> 50 creates a component generating an empty string while always succeeding: 51 </p> 52<pre class="programlisting"><span class="identifier">eps</span> <span class="comment">// always emits a zero-length string</span> 53</pre> 54<p> 55 This form is usually used to trigger a semantic action unconditionally. 56 For example, it is useful in triggering error messages when a set of 57 alternatives fail: 58 </p> 59<pre class="programlisting"><span class="identifier">r</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">eps</span><span class="special">[</span><span class="identifier">error</span><span class="special">()];</span> <span class="comment">// Call error if a, b, and c fail to generate</span> 60</pre> 61<h6> 62<a name="spirit.karma.reference.auxiliary.eps.h2"></a> 63 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.semantic_predicate"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.semantic_predicate">Semantic 64 Predicate</a> 65 </h6> 66<p> 67 The <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code> 68 component generates an empty string as well, but succeeds only if <code class="computeroutput"><span class="identifier">b</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> 69 and fails otherwise. It's lazy variant <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">fb</span><span class="special">)</span></code> is equivalent to <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code> except it evaluates the supplied function 70 <code class="computeroutput"><span class="identifier">fb</span></code> at generate time, 71 while using the return value as the criteria to succeed. 72 </p> 73<p> 74 Semantic predicates allow you to attach a conditional function anywhere 75 in the grammar. In this role, the epsilon takes a <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy 76 Argument</a> that returns <code class="computeroutput"><span class="keyword">true</span></code> 77 or <code class="computeroutput"><span class="keyword">false</span></code>. The <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy 78 Argument</a> is typically a test that is called to resolve ambiguity 79 in the grammar. A generator failure will be reported when the <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy 80 Argument</a> result evaluates to <code class="computeroutput"><span class="keyword">false</span></code>. 81 Otherwise an empty string will be emitted. The general form is: 82 </p> 83<pre class="programlisting"><span class="identifier">eps_p</span><span class="special">(</span><span class="identifier">fb</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">rest</span><span class="special">;</span> 84</pre> 85<p> 86 The <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy 87 Argument</a> <code class="computeroutput"><span class="identifier">fb</span></code> is 88 called to do a semantic test. If the test returns true, <code class="computeroutput"><span class="identifier">rest</span></code> will be evaluated. Otherwise, 89 the production will return early without ever touching rest. 90 </p> 91<h6> 92<a name="spirit.karma.reference.auxiliary.eps.h3"></a> 93 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.header"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.header">Header</a> 94 </h6> 95<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/karma/auxiliary/eps.hpp></span> 96<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_eps</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 97</pre> 98<p> 99 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 100 </p> 101<h6> 102<a name="spirit.karma.reference.auxiliary.eps.h4"></a> 103 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.namespace"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.namespace">Namespace</a> 104 </h6> 105<div class="informaltable"><table class="table"> 106<colgroup><col></colgroup> 107<thead><tr><th> 108 <p> 109 Name 110 </p> 111 </th></tr></thead> 112<tbody><tr><td> 113 <p> 114 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">eps</span> <span class="comment">// alias: 115 boost::spirit::karma::eps</span></code> 116 </p> 117 </td></tr></tbody> 118</table></div> 119<h6> 120<a name="spirit.karma.reference.auxiliary.eps.h5"></a> 121 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.model_of"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.model_of">Model 122 of</a> 123 </h6> 124<div class="blockquote"><blockquote class="blockquote"><p> 125 <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a> 126 </p></blockquote></div> 127<div class="variablelist"> 128<p class="title"><b>Notation</b></p> 129<dl class="variablelist"> 130<dt><span class="term"><code class="computeroutput"><span class="identifier">b</span></code></span></dt> 131<dd><p> 132 A boolean value. 133 </p></dd> 134<dt><span class="term"><code class="computeroutput"><span class="identifier">fb</span></code></span></dt> 135<dd><p> 136 A <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy 137 Argument</a> that evaluates to a boolean value. 138 </p></dd> 139</dl> 140</div> 141<h6> 142<a name="spirit.karma.reference.auxiliary.eps.h6"></a> 143 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.expression_semantics"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.expression_semantics">Expression 144 Semantics</a> 145 </h6> 146<p> 147 Semantics of an expression is defined only where it differs from, or 148 is not defined in <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>. 149 </p> 150<div class="informaltable"><table class="table"> 151<colgroup> 152<col> 153<col> 154</colgroup> 155<thead><tr> 156<th> 157 <p> 158 Expression 159 </p> 160 </th> 161<th> 162 <p> 163 Semantics 164 </p> 165 </th> 166</tr></thead> 167<tbody> 168<tr> 169<td> 170 <p> 171 <code class="computeroutput"><span class="identifier">eps</span></code> 172 </p> 173 </td> 174<td> 175 <p> 176 Creates a component generating an empty string. Succeeds always. 177 </p> 178 </td> 179</tr> 180<tr> 181<td> 182 <p> 183 <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code> 184 </p> 185 </td> 186<td> 187 <p> 188 Creates a component generating an empty string. Succeeds if 189 <code class="computeroutput"><span class="identifier">b</span></code> is <code class="computeroutput"><span class="keyword">true</span></code> (unless the underlying 190 output stream reports an error). 191 </p> 192 </td> 193</tr> 194<tr> 195<td> 196 <p> 197 <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">fb</span><span class="special">)</span></code> 198 </p> 199 </td> 200<td> 201 <p> 202 Creates a component generating an empty string. Succeeds if 203 <code class="computeroutput"><span class="identifier">fb</span></code> returns 204 <code class="computeroutput"><span class="keyword">true</span></code> at generate 205 time (unless the underlying output stream reports an error). 206 </p> 207 </td> 208</tr> 209</tbody> 210</table></div> 211<h6> 212<a name="spirit.karma.reference.auxiliary.eps.h7"></a> 213 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.attributes"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.attributes">Attributes</a> 214 </h6> 215<div class="informaltable"><table class="table"> 216<colgroup> 217<col> 218<col> 219</colgroup> 220<thead><tr> 221<th> 222 <p> 223 Expression 224 </p> 225 </th> 226<th> 227 <p> 228 Attribute 229 </p> 230 </th> 231</tr></thead> 232<tbody> 233<tr> 234<td> 235 <p> 236 <code class="computeroutput"><span class="identifier">eps</span></code> 237 </p> 238 </td> 239<td> 240 <p> 241 <code class="computeroutput"><span class="identifier">unused</span></code> 242 </p> 243 </td> 244</tr> 245<tr> 246<td> 247 <p> 248 <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">b</span><span class="special">)</span></code> 249 </p> 250 </td> 251<td> 252 <p> 253 <code class="computeroutput"><span class="identifier">unused</span></code> 254 </p> 255 </td> 256</tr> 257<tr> 258<td> 259 <p> 260 <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">fb</span><span class="special">)</span></code> 261 </p> 262 </td> 263<td> 264 <p> 265 <code class="computeroutput"><span class="identifier">unused</span></code> 266 </p> 267 </td> 268</tr> 269</tbody> 270</table></div> 271<h6> 272<a name="spirit.karma.reference.auxiliary.eps.h8"></a> 273 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.complexity"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.complexity">Complexity</a> 274 </h6> 275<div class="blockquote"><blockquote class="blockquote"><p> 276 O(1) 277 </p></blockquote></div> 278<p> 279 The complexity is constant as no output is generated. 280 </p> 281<h6> 282<a name="spirit.karma.reference.auxiliary.eps.h9"></a> 283 <span class="phrase"><a name="spirit.karma.reference.auxiliary.eps.example"></a></span><a class="link" href="eps.html#spirit.karma.reference.auxiliary.eps.example">Example</a> 284 </h6> 285<div class="note"><table border="0" summary="Note"> 286<tr> 287<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 288<th align="left">Note</th> 289</tr> 290<tr><td align="left" valign="top"><p> 291 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> 292 section. 293 </p></td></tr> 294</table></div> 295<p> 296 Some includes: 297 </p> 298<p> 299</p> 300<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> 301<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> 302<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> 303<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> 304<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> 305<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 306<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 307</pre> 308<p> 309 </p> 310<p> 311 Some using declarations: 312 </p> 313<p> 314</p> 315<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">eps</span><span class="special">;</span> 316<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> 317</pre> 318<p> 319 </p> 320<p> 321 Basic usage of the <code class="computeroutput"><span class="identifier">eps</span></code> 322 generator: 323 </p> 324<p> 325</p> 326<pre class="programlisting"><span class="identifier">test_generator</span><span class="special">(</span><span class="string">"abc"</span><span class="special">,</span> <span class="identifier">eps</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">val</span><span class="special">(</span><span class="string">"starting eps example"</span><span class="special">)]</span> <span class="special"><<</span> <span class="string">"abc"</span><span class="special">);</span> 327<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"abc"</span><span class="special">,</span> <span class="identifier">eps</span><span class="special">(</span><span class="keyword">true</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"abc"</span><span class="special">);</span> 328<span class="identifier">test_generator</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">eps</span><span class="special">(</span><span class="keyword">false</span><span class="special">)</span> <span class="special"><<</span> <span class="string">"abc"</span><span class="special">);</span> <span class="comment">// fails as eps expression is 'false'</span> 329</pre> 330<p> 331 </p> 332</div> 333<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 334<td align="left"></td> 335<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 336 Distributed under the Boost Software License, Version 1.0. (See accompanying 337 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>) 338 </p> 339</div></td> 340</tr></table> 341<hr> 342<div class="spirit-nav"> 343<a accesskey="p" href="eol.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../auxiliary.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="lazy.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 344</div> 345</body> 346</html> 347
