libs/spirit/doc/html/spirit/qi/reference/auxiliary/eps.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Epsilon Parser (eps)</title>
   5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="../../../../index.html" title="Spirit 2.5.2">
   8 <link rel="up" href="../auxiliary.html" title="Auxiliary Parsers">
   9 <link rel="prev" href="eoi.html" title="End of Input Parser (eoi)">
  10 <link rel="next" href="lazy.html" title="Lazy Parser (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="eoi.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.qi.reference.auxiliary.eps"></a><a class="link" href="eps.html" title="Epsilon Parser (eps)">Epsilon Parser
  28           (<code class="computeroutput"><span class="identifier">eps</span></code>)</a>
  29 </h5></div></div></div>
  30 <h6>
  31 <a name="spirit.qi.reference.auxiliary.eps.h0"></a>
  32             <span><a name="spirit.qi.reference.auxiliary.eps.description"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.description">Description</a>
  33           </h6>
  34 <p>
  35             The Epsilon (<code class="computeroutput"><span class="identifier">eps</span></code>) is
  36             a multi-purpose parser that returns a zero length match.
  37           </p>
  38 <h6>
  39 <a name="spirit.qi.reference.auxiliary.eps.h1"></a>
  40             <span><a name="spirit.qi.reference.auxiliary.eps.simple_form"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.simple_form">Simple
  41             Form</a>
  42           </h6>
  43 <p>
  44             In its simplest form, <code class="computeroutput"><span class="identifier">eps</span></code>
  45             matches the null string and always returns a match of zero length:
  46           </p>
  47 <pre class="programlisting"><span class="identifier">eps</span> <span class="comment">// always returns a zero-length match</span>
  48 </pre>
  49 <p>
  50             This form is usually used to trigger a semantic action unconditionally.
  51             For example, it is useful in triggering error messages when a set of
  52             alternatives fail:
  53           </p>
  54 <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 match</span>
  55 </pre>
  56 <h6>
  57 <a name="spirit.qi.reference.auxiliary.eps.h2"></a>
  58             <span><a name="spirit.qi.reference.auxiliary.eps.semantic_predicate"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.semantic_predicate">Semantic
  59             Predicate</a>
  60           </h6>
  61 <p>
  62             Semantic predicates allow you to attach a conditional function anywhere
  63             in the grammar. In this role, the epsilon takes a <a class="link" href="../basics.html#spirit.qi.reference.basics.lazy_argument">Lazy
  64             Argument</a> that returns <code class="computeroutput"><span class="keyword">true</span></code>
  65             or <code class="computeroutput"><span class="keyword">false</span></code>. The <a class="link" href="../basics.html#spirit.qi.reference.basics.lazy_argument">Lazy
  66             Argument</a> is typically a test that is called to resolve ambiguity
  67             in the grammar. A parse failure will be reported when the <a class="link" href="../basics.html#spirit.qi.reference.basics.lazy_argument">Lazy
  68             Argument</a> result evaluates to <code class="computeroutput"><span class="keyword">false</span></code>.
  69             Otherwise an empty match will be reported. The general form is:
  70           </p>
  71 <pre class="programlisting"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="identifier">rest</span><span class="special">;</span>
  72 </pre>
  73 <p>
  74             The <a class="link" href="../basics.html#spirit.qi.reference.basics.lazy_argument">Lazy Argument</a>
  75             <code class="computeroutput"><span class="identifier">f</span></code> is called to do a semantic
  76             test (say, checking if a symbol is in the symbol table). If test returns
  77             true, <code class="computeroutput"><span class="identifier">rest</span></code> will be evaluated.
  78             Otherwise, the production will return early with a no-match without ever
  79             touching rest.
  80           </p>
  81 <h6>
  82 <a name="spirit.qi.reference.auxiliary.eps.h3"></a>
  83             <span><a name="spirit.qi.reference.auxiliary.eps.header"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.header">Header</a>
  84           </h6>
  85 <pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/qi/auxiliary/eps.hpp&gt;</span>
  86 <span class="preprocessor">#include</span> <span class="special">&lt;</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_eps</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  87 </pre>
  88 <p>
  89             Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
  90           </p>
  91 <h6>
  92 <a name="spirit.qi.reference.auxiliary.eps.h4"></a>
  93             <span><a name="spirit.qi.reference.auxiliary.eps.namespace"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.namespace">Namespace</a>
  94           </h6>
  95 <div class="informaltable"><table class="table">
  96 <colgroup><col></colgroup>
  97 <thead><tr><th>
  98                     <p>
  99                       Name
 100                     </p>
 101                   </th></tr></thead>
 102 <tbody><tr><td>
 103                     <p>
 104                       <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:
 105                       boost::spirit::qi::eps</span></code>
 106                     </p>
 107                   </td></tr></tbody>
 108 </table></div>
 109 <h6>
 110 <a name="spirit.qi.reference.auxiliary.eps.h5"></a>
 111             <span><a name="spirit.qi.reference.auxiliary.eps.model_of"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.model_of">Model
 112             of</a>
 113           </h6>
 114 <div class="blockquote"><blockquote class="blockquote"><p>
 115               <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a>
 116             </p></blockquote></div>
 117 <div class="variablelist">
 118 <p class="title"><b>Notation</b></p>
 119 <dl>
 120 <dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt>
 121 <dd><p>
 122                   A <a class="link" href="../basics.html#spirit.qi.reference.basics.lazy_argument">Lazy
 123                   Argument</a> that evaluates <code class="computeroutput"><span class="keyword">bool</span></code>.
 124                 </p></dd>
 125 </dl>
 126 </div>
 127 <h6>
 128 <a name="spirit.qi.reference.auxiliary.eps.h6"></a>
 129             <span><a name="spirit.qi.reference.auxiliary.eps.expression_semantics"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.expression_semantics">Expression
 130             Semantics</a>
 131           </h6>
 132 <p>
 133             Semantics of an expression is defined only where it differs from, or
 134             is not defined in <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a>.
 135           </p>
 136 <div class="informaltable"><table class="table">
 137 <colgroup>
 138 <col>
 139 <col>
 140 </colgroup>
 141 <thead><tr>
 142 <th>
 143                     <p>
 144                       Expression
 145                     </p>
 146                   </th>
 147 <th>
 148                     <p>
 149                       Semantics
 150                     </p>
 151                   </th>
 152 </tr></thead>
 153 <tbody>
 154 <tr>
 155 <td>
 156                     <p>
 157                       <code class="computeroutput"><span class="identifier">eps</span></code>
 158                     </p>
 159                   </td>
 160 <td>
 161                     <p>
 162                       Match an empty string (always matches).
 163                     </p>
 164                   </td>
 165 </tr>
 166 <tr>
 167 <td>
 168                     <p>
 169                       <code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>
 170                     </p>
 171                   </td>
 172 <td>
 173                     <p>
 174                       If <code class="computeroutput"><span class="identifier">f</span></code> evaluates
 175                       to <code class="computeroutput"><span class="keyword">true</span></code>, return
 176                       a zero length match.
 177                     </p>
 178                   </td>
 179 </tr>
 180 </tbody>
 181 </table></div>
 182 <h6>
 183 <a name="spirit.qi.reference.auxiliary.eps.h7"></a>
 184             <span><a name="spirit.qi.reference.auxiliary.eps.attributes"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.attributes">Attributes</a>
 185           </h6>
 186 <div class="informaltable"><table class="table">
 187 <colgroup>
 188 <col>
 189 <col>
 190 </colgroup>
 191 <thead><tr>
 192 <th>
 193                     <p>
 194                       Expression
 195                     </p>
 196                   </th>
 197 <th>
 198                     <p>
 199                       Attribute
 200                     </p>
 201                   </th>
 202 </tr></thead>
 203 <tbody><tr>
 204 <td>
 205                     <p>
 206                       <code class="computeroutput"><span class="identifier">eps</span></code>
 207                     </p>
 208                   </td>
 209 <td>
 210                     <p>
 211                       <code class="computeroutput"><span class="identifier">unused</span></code>
 212                     </p>
 213                   </td>
 214 </tr></tbody>
 215 </table></div>
 216 <h6>
 217 <a name="spirit.qi.reference.auxiliary.eps.h8"></a>
 218             <span><a name="spirit.qi.reference.auxiliary.eps.complexity"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.complexity">Complexity</a>
 219           </h6>
 220 <div class="blockquote"><blockquote class="blockquote"><p>
 221               For plain (<code class="computeroutput"><span class="identifier">eps</span></code>) the
 222               complexity is O(1). For Semantic predicates (<code class="computeroutput"><span class="identifier">eps</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>) the complexity is defined by the
 223               function <code class="computeroutput"><span class="identifier">f</span></code>.
 224             </p></blockquote></div>
 225 <h6>
 226 <a name="spirit.qi.reference.auxiliary.eps.h9"></a>
 227             <span><a name="spirit.qi.reference.auxiliary.eps.example"></a></span><a class="link" href="eps.html#spirit.qi.reference.auxiliary.eps.example">Example</a>
 228           </h6>
 229 <div class="note"><table border="0" summary="Note">
 230 <tr>
 231 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
 232 <th align="left">Note</th>
 233 </tr>
 234 <tr><td align="left" valign="top"><p>
 235               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>
 236               section.
 237             </p></td></tr>
 238 </table></div>
 239 <p>
 240             Some using declarations:
 241           </p>
 242 <p>
 243 </p>
 244 <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">qi</span><span class="special">::</span><span class="identifier">eps</span><span class="special">;</span>
 245 <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>
 246 <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>
 247 <span class="keyword">namespace</span> <span class="identifier">phx</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">phoenix</span><span class="special">;</span>
 248 </pre>
 249 <p>
 250           </p>
 251 <p>
 252             Basic <code class="computeroutput"><span class="identifier">eps</span></code>:
 253           </p>
 254 <p>
 255 </p>
 256 <pre class="programlisting"><span class="identifier">test_parser</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">eps</span><span class="special">);</span> <span class="comment">// always matches</span>
 257 </pre>
 258 <p>
 259           </p>
 260 <p>
 261             This example simulates the "classic" <code class="computeroutput"><span class="identifier">if_p</span></code>
 262             parser. Here, <code class="computeroutput"><span class="identifier">int_</span></code> will
 263             be tried only if the condition, <code class="computeroutput"><span class="identifier">c</span></code>,
 264             is true.
 265           </p>
 266 <p>
 267 </p>
 268 <pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">c</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> <span class="comment">// a flag</span>
 269 <span class="identifier">test_parser</span><span class="special">(</span><span class="string">"1234"</span><span class="special">,</span> <span class="identifier">eps</span><span class="special">(</span><span class="identifier">phx</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">);</span>
 270 </pre>
 271 <p>
 272           </p>
 273 <p>
 274             This example simulates the "classic" <code class="computeroutput"><span class="identifier">while_p</span></code>
 275             parser. Here, the kleene loop will exit once the condition, <code class="computeroutput"><span class="identifier">c</span></code>, becomes true. Notice that the condition,
 276             <code class="computeroutput"><span class="identifier">c</span></code>, is turned to <code class="computeroutput"><span class="keyword">false</span></code> when we get to parse <code class="computeroutput"><span class="number">4</span></code>.
 277           </p>
 278 <p>
 279 </p>
 280 <pre class="programlisting"><span class="identifier">test_phrase_parser</span><span class="special">(</span><span class="string">"1 2 3 4"</span><span class="special">,</span>
 281     <span class="special">*(</span><span class="identifier">eps</span><span class="special">(</span><span class="identifier">phx</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">)</span> <span class="special">&gt;&gt;</span> <span class="identifier">int_</span><span class="special">[</span><span class="identifier">phx</span><span class="special">::</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">_1</span> <span class="special">==</span> <span class="number">4</span><span class="special">)]));</span>
 282 </pre>
 283 <p>
 284           </p>
 285 </div>
 286 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 287 <td align="left"></td>
 288 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 289         Distributed under the Boost Software License, Version 1.0. (See accompanying
 290         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>)
 291       </p>
 292 </div></td>
 293 </tr></table>
 294 <hr>
 295 <div class="spirit-nav">
 296 <a accesskey="p" href="eoi.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>
 297 </div>
 298 </body>
 299 </html>