ceph/src/boost/libs/phoenix/doc/html/phoenix/inside/expression.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Phoenix Expressions</title>
   5 <link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Phoenix 3.2.0">
   8 <link rel="up" href="../inside.html" title="Inside Phoenix">
   9 <link rel="prev" href="actor.html" title="Actors in Detail">
  10 <link rel="next" href="expression/boilerplate_macros.html" title="Boilerplate Macros">
  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="actor.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inside.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="expression/boilerplate_macros.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="phoenix.inside.expression"></a><a class="link" href="expression.html" title="Phoenix Expressions">Phoenix Expressions</a>
  28 </h3></div></div></div>
  29 <div class="toc"><dl><dt><span class="section"><a href="expression/boilerplate_macros.html">Boilerplate
  30         Macros</a></span></dt></dl></div>
  31 <p>
  32         A Phoenix Expression is a model of the <a href="http://www.boost.org/doc/libs/release/doc/html/Expr.html" target="_top">Proto
  33         Expression</a> Concept. These expressions are wrapped inside an <a class="link" href="actor.html" title="Actors in Detail">Actor</a> template. The <code class="computeroutput"><span class="identifier">actor</span></code>
  34         provides the function call operator which evaluates the expressions. The
  35         <code class="computeroutput"><span class="identifier">actor</span></code> is the domain specific
  36         wrapper around Phoenix expressions.
  37       </p>
  38 <p>
  39         By design, Phoenix Expressions do not carry any information on how they will
  40         be evaluated later on. They are the data structure on which the <code class="computeroutput"><span class="identifier">Actions</span></code> will work.
  41       </p>
  42 <p>
  43         The library provides a convenience template to define expressions:
  44       </p>
  45 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span><span class="special">&gt;</span> <span class="identifier">Actor</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Tag</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A0</span><span class="special">,</span> <span class="special">...,</span> <span class="keyword">typename</span> <span class="identifier">A1</span><span class="special">&gt;</span>
  46 <span class="keyword">struct</span> <span class="identifier">expr_ext</span>
  47     <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">transform</span><span class="special">&lt;</span><span class="identifier">expr_ext</span><span class="special">&lt;</span><span class="identifier">Actor</span><span class="special">,</span> <span class="identifier">Tag</span><span class="special">,</span> <span class="identifier">A0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">A1</span><span class="special">&gt;</span> <span class="special">&gt;</span>
  48 <span class="special">{</span>
  49     <span class="keyword">typedef</span> <span class="emphasis"><em>unspecified</em></span> <span class="identifier">base_expr</span><span class="special">;</span>
  50     <span class="keyword">typedef</span> <span class="identifier">Actor</span><span class="special">&lt;</span><span class="identifier">base_expr</span><span class="special">&gt;</span> <span class="identifier">type</span><span class="special">;</span>
  51
  52     <span class="keyword">typedef</span> <span class="emphasis"><em>unspecified</em></span> <span class="identifier">proto_grammar</span><span class="special">;</span>
  53
  54     <span class="keyword">static</span> <span class="identifier">type</span> <span class="identifier">make</span><span class="special">(</span><span class="identifier">A0</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">A1</span> <span class="identifier">a1</span><span class="special">);</span>
  55 <span class="special">};</span>
  56
  57 <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Tag</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">A0</span><span class="special">,</span> <span class="special">...,</span> <span class="keyword">typename</span> <span class="identifier">A1</span><span class="special">&gt;</span>
  58 <span class="keyword">struct</span> <span class="identifier">expr</span> <span class="special">:</span> <span class="identifier">expr_ext</span><span class="special">&lt;</span><span class="identifier">actor</span><span class="special">,</span> <span class="identifier">Tag</span><span class="special">,</span> <span class="identifier">A0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">A1</span><span class="special">&gt;</span> <span class="special">{};</span>
  59 </pre>
  60 <p>
  61         <span class="bold"><strong>Notation</strong></span>
  62       </p>
  63 <div class="variablelist">
  64 <p class="title"><b></b></p>
  65 <dl>
  66 <dt><span class="term"><code class="computeroutput"><span class="identifier">A0</span><span class="special">...</span><span class="identifier">AN</span></code></span></dt>
  67 <dd><p>
  68               Child node types
  69             </p></dd>
  70 <dt><span class="term"><code class="computeroutput"><span class="identifier">a0</span><span class="special">...</span><span class="identifier">aN</span></code></span></dt>
  71 <dd><p>
  72               Child node objects
  73             </p></dd>
  74 <dt><span class="term"><code class="computeroutput"><span class="identifier">G0</span><span class="special">...</span><span class="identifier">GN</span></code></span></dt>
  75 <dd><p>
  76               <a href="http://www.boost.org/doc/libs/release/libs/proto/index.html" target="_top">Boost.Proto</a>
  77               grammar types
  78             </p></dd>
  79 </dl>
  80 </div>
  81 <p>
  82         <span class="bold"><strong>Expression Semantics</strong></span>
  83       </p>
  84 <div class="informaltable"><table class="table">
  85 <colgroup>
  86 <col>
  87 <col>
  88 </colgroup>
  89 <thead><tr>
  90 <th>
  91                 <p>
  92                   Expression
  93                 </p>
  94               </th>
  95 <th>
  96                 <p>
  97                   Semantics
  98                 </p>
  99               </th>
 100 </tr></thead>
 101 <tbody>
 102 <tr>
 103 <td>
 104                 <p>
 105                   <code class="computeroutput"><span class="identifier">expr</span><span class="special">&lt;</span><span class="identifier">Tag</span><span class="special">,</span>
 106                   <span class="identifier">A0</span><span class="special">...</span><span class="identifier">AN</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
 107                 </p>
 108               </td>
 109 <td>
 110                 <p>
 111                   The type of Expression having tag <code class="computeroutput"><span class="identifier">Tag</span></code>
 112                   and <code class="computeroutput"><span class="identifier">A0</span><span class="special">...</span><span class="identifier">AN</span></code> children
 113                 </p>
 114               </td>
 115 </tr>
 116 <tr>
 117 <td>
 118                 <p>
 119                   <code class="computeroutput"><span class="identifier">expr</span><span class="special">&lt;</span><span class="identifier">Tag</span><span class="special">,</span>
 120                   <span class="identifier">G0</span><span class="special">...</span><span class="identifier">GN</span><span class="special">&gt;</span></code>
 121                 </p>
 122               </td>
 123 <td>
 124                 <p>
 125                   A <a href="http://www.boost.org/doc/libs/release/libs/proto/index.html" target="_top">Boost.Proto</a>
 126                   grammar and <a href="http://www.boost.org/doc/libs/release/doc/html/boost/proto/pass_through.html" target="_top">Proto
 127                   Pass Through Transform</a>
 128                 </p>
 129               </td>
 130 </tr>
 131 <tr>
 132 <td>
 133                 <p>
 134                   <code class="computeroutput"><span class="identifier">expr</span><span class="special">&lt;</span><span class="identifier">Tag</span><span class="special">,</span>
 135                   <span class="identifier">A0</span><span class="special">...</span><span class="identifier">AN</span><span class="special">&gt;::</span><span class="identifier">make</span><span class="special">(</span><span class="identifier">a0</span><span class="special">...</span><span class="identifier">aN</span><span class="special">)</span></code>
 136                 </p>
 137               </td>
 138 <td>
 139                 <p>
 140                   Returns a Phoenix Expression
 141                 </p>
 142               </td>
 143 </tr>
 144 </tbody>
 145 </table></div>
 146 <div class="note"><table border="0" summary="Note">
 147 <tr>
 148 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
 149 <th align="left">Note</th>
 150 </tr>
 151 <tr><td align="left" valign="top"><p>
 152           You might have noticed the template template argument <code class="computeroutput"><span class="identifier">Actor</span></code>
 153           used in <code class="computeroutput"><span class="identifier">expr_ext</span></code>. This
 154           can be a user supplied custom Actor adding other member functions or objects
 155           than the default <code class="computeroutput"><span class="identifier">actor</span></code>
 156           template. See <a class="link" href="../examples/extending_actors.html" title="Extending Actors">Extending
 157           Actors</a> for more details.
 158         </p></td></tr>
 159 </table></div>
 160 <h5>
 161 <a name="phoenix.inside.expression.h0"></a>
 162         <span><a name="phoenix.inside.expression.meta_grammar"></a></span><a class="link" href="expression.html#phoenix.inside.expression.meta_grammar">meta_grammar</a>
 163       </h5>
 164 <p>
 165         Defining expressions is only part of the game to make it a valid Phoenix
 166         Expression. In order to use the expressions in the Phoenix domain, we need
 167         to "register" them to our grammar.
 168       </p>
 169 <p>
 170         The <code class="computeroutput"><span class="identifier">meta_grammar</span></code> is a struct
 171         for exactly that purpose. It is an openly extendable <a href="http://www.boost.org/doc/libs/release/libs/proto/index.html" target="_top">Boost.Proto</a>
 172         Grammar:
 173       </p>
 174 <pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">meta_grammar</span>
 175     <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">switch_</span><span class="special">&lt;</span><span class="identifier">meta_grammar</span><span class="special">&gt;</span>
 176 <span class="special">{</span>
 177     <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Tag</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Dummy</span><span class="special">&gt;</span>
 178     <span class="keyword">struct</span> <span class="identifier">case_</span>
 179         <span class="special">:</span> <span class="identifier">proto</span><span class="special">::</span><span class="identifier">not_</span><span class="special">&lt;</span><span class="identifier">proto</span><span class="special">::</span><span class="identifier">_</span><span class="special">&gt;</span>
 180     <span class="special">{};</span>
 181 <span class="special">};</span>
 182 </pre>
 183 <p>
 184         As you can see, by default the <code class="computeroutput"><span class="identifier">meta_grammar</span></code>
 185         matches nothing. With every <a class="link" href="../modules.html" title="Modules">Module</a>
 186         you include this grammar gets extended by various expressions.
 187       </p>
 188 <h5>
 189 <a name="phoenix.inside.expression.h1"></a>
 190         <span><a name="phoenix.inside.expression.example"></a></span><a class="link" href="expression.html#phoenix.inside.expression.example">Example</a>
 191       </h5>
 192 <p>
 193         Define an expression:
 194       </p>
 195 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Lhs</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Rhs</span><span class="special">&gt;</span>
 196 <span class="keyword">struct</span> <span class="identifier">plus</span>
 197     <span class="special">:</span> <span class="identifier">expr</span><span class="special">&lt;</span><span class="identifier">proto</span><span class="special">::</span><span class="identifier">tag</span><span class="special">::</span><span class="identifier">plus</span><span class="special">,</span> <span class="identifier">Lhs</span><span class="special">,</span> <span class="identifier">Rhs</span><span class="special">&gt;</span>
 198 <span class="special">{};</span>
 199 </pre>
 200 <p>
 201         And add it to the grammar:
 202       </p>
 203 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 204 <span class="keyword">struct</span> <span class="identifier">meta_grammar</span><span class="special">::</span><span class="identifier">case_</span><span class="special">&lt;</span><span class="identifier">proto</span><span class="special">::</span><span class="identifier">tag</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&gt;</span>
 205     <span class="special">:</span> <span class="identifier">enable_rule</span><span class="special">&lt;</span>
 206         <span class="identifier">plus</span><span class="special">&lt;</span>
 207             <span class="identifier">meta_grammar</span>
 208           <span class="special">,</span> <span class="identifier">meta_grammar</span>
 209         <span class="special">&gt;</span>
 210     <span class="special">&gt;</span>
 211 <span class="special">{};</span>
 212 </pre>
 213 <p>
 214         Define a generator function to make the life of our potential users easier:
 215       </p>
 216 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Lhs</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Rhs</span><span class="special">&gt;</span>
 217 <span class="keyword">typename</span> <span class="identifier">plus</span><span class="special">&lt;</span><span class="identifier">Lhs</span><span class="special">,</span> <span class="identifier">Rhs</span><span class="special">&gt;::</span><span class="identifier">type</span>
 218 <span class="identifier">plus</span><span class="special">(</span><span class="identifier">Lhs</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">Rhs</span> <span class="keyword">const</span> <span class="special">&amp;</span> <span class="identifier">rhs</span><span class="special">)</span>
 219 <span class="special">{</span>
 220     <span class="keyword">return</span> <span class="identifier">expression</span><span class="special">::</span><span class="identifier">plus</span><span class="special">&lt;</span><span class="identifier">Lhs</span><span class="special">,</span> <span class="identifier">Rhs</span><span class="special">&gt;::</span><span class="identifier">make</span><span class="special">(</span><span class="identifier">lhs</span><span class="special">,</span> <span class="identifier">rhs</span><span class="special">);</span>
 221 <span class="special">}</span>
 222 </pre>
 223 <p>
 224         Look if it really works:
 225       </p>
 226 <pre class="programlisting"><span class="identifier">plus</span><span class="special">(</span><span class="number">6</span><span class="special">,</span> <span class="number">5</span><span class="special">)();</span>
 227 </pre>
 228 <p>
 229         returns 11!
 230       </p>
 231 <pre class="programlisting"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">display_expr</span><span class="special">(</span><span class="identifier">plus</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">6</span><span class="special">));</span>
 232 </pre>
 233 <p>
 234         prints:
 235       </p>
 236 <pre class="programlisting"><span class="identifier">plus</span><span class="special">(</span>
 237     <span class="identifier">terminal</span><span class="special">(</span><span class="number">6</span><span class="special">)</span>
 238   <span class="special">,</span> <span class="identifier">terminal</span><span class="special">(</span><span class="number">5</span><span class="special">)</span>
 239 <span class="special">)</span>
 240 </pre>
 241 <p>
 242         See <a href="../../../../example/define_expression.cpp" target="_top">define_expression.cpp</a>
 243         for the full example.
 244       </p>
 245 <div class="note"><table border="0" summary="Note">
 246 <tr>
 247 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
 248 <th align="left">Note</th>
 249 </tr>
 250 <tr><td align="left" valign="top"><p>
 251           The example shown here only works because <code class="computeroutput"><span class="identifier">default_actions</span></code>
 252           knows how to handle an expression having the <code class="computeroutput"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">tag</span><span class="special">::</span><span class="identifier">plus</span></code>
 253           and two children. This is because <code class="computeroutput"><span class="identifier">default_actions</span></code>
 254           uses the <code class="computeroutput"><span class="identifier">proto</span><span class="special">::</span><span class="identifier">_default</span><span class="special">&lt;</span><span class="identifier">meta_grammar</span><span class="special">&gt;</span></code>
 255           transform to evaluate operators and functions. Learn more about actions
 256           <a class="link" href="actions.html" title="More on Actions">here</a>.
 257         </p></td></tr>
 258 </table></div>
 259 </div>
 260 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 261 <td align="left"></td>
 262 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2005, 2010, 2014, 2015 Joel de Guzman, Dan Marsden, Thomas
 263       Heller, John Fletcher<p>
 264         Distributed under the Boost Software License, Version 1.0. (See accompanying
 265         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>)
 266       </p>
 267 </div></td>
 268 </tr></table>
 269 <hr>
 270 <div class="spirit-nav">
 271 <a accesskey="p" href="actor.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../inside.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="expression/boilerplate_macros.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 272 </div>
 273 </body>
 274 </html>