ceph/src/boost/libs/spirit/classic/doc/stored_rule.html

   1 <html>
   2 <head>
   3 <title>Storable Rules</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <link rel="stylesheet" href="theme/style.css" type="text/css">
   6 </head>
   7
   8 <body>
   9 <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2">
  10   <tr>
  11     <td width="10">
  12     </td>
  13     <td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Storable
  14       Rules</b></font></td>
  15     <td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" width="112" height="48" align="right" border="0"></a></td>
  16   </tr>
  17 </table>
  18 <br>
  19 <table border="0">
  20   <tr>
  21     <td width="10"></td>
  22     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
  23     <td width="30"><a href="stored_rule.html"><img src="theme/l_arr.gif" border="0"></a></td>
  24     <td width="30"><a href="the_lazy_parser.html"><img src="theme/r_arr.gif" border="0"></a></td>
  25   </tr>
  26 </table>
  27 <p>The rule is a weird C++ citizen, unlike any other C++ object. It does not have
  28   the proper copy and assignment semantics and cannot be stored and passed around
  29   by value. You cannot store rules in STL containers (vector, stack, etc) for
  30   later use and you cannot  pass and return rules to and from functions by value.</p>
  31 <p>EBNF is primarily declarative. Like in functional programming, an EBNF grammar
  32   is a static recipe and there's no notion of do this then that. However, in Spirit,
  33   we managed to coax imperative C++ to take in declarative EBNF. Hah! Fun!...
  34   We did that by masquerading the C++ assignment operator to mimic EBNF's <tt>::=</tt>.
  35   To do that, we gave the rule class' assignment operator and copy constructor
  36   a different meaning and semantics. The downside is that doing so made the rule
  37   unlike any other C++ object. You can't copy it. You can't assign it. </p>
  38 <p>We want to have the dynamic nature of C++ to our advantage. We've seen dynamic
  39   Spirit in action here and there. There are indeed some interesting applications
  40   of dynamic parsers using Spirit. Yet, we will not fully utilize the power of
  41   dynamic parsing, unless we have a rule that behaves like any other good C++
  42   object. With such a beast, we can write full parsers that's defined at run time,
  43   as opposed to compile time.</p>
  44 <p>We now have dynamic rules: <tt>stored_rules</tt>. Basically they are rules
  45   with perfect C++ assignment/copy-constructor semantics. This means that <tt>stored_rules</tt>
  46   can be stored in containers and/or dynamically created at run-time.</p>
  47 <pre><code><font color="#000000"><span class=identifier>    </span><span class=keyword>template</span><span class=special>&lt;
  48         </span><span class=keyword>typename </span><span class=identifier>ScannerT </span><span class=special>= </span><span class=identifier>scanner</span><span class=special>&lt;&gt;,
  49         </span><span class=keyword>typename </span><span class=identifier>ContextT </span><span class=special>= </span><span class=identifier>parser_context</span><span class=special>&lt;&gt;</span><span class=identifier>,
  50         </span><span class="keyword">typename</span><span class=identifier> TagT </span><span class="special">=</span><span class=identifier> parser_address_tag</span><span class=special>&gt;
  51     </span><span class=keyword>class </span><span class=identifier>stored_rule</span><span class=special>;</span></font></code></pre>
  52 <p>The interface is exactly the same as with the rule class (see the <a href="rule.html">section
  53   on rules</a> for more information regarding the API). The only difference is
  54   with the copy and assignment semantics. Now, with <tt>stored_rule</tt>s, we
  55   can dynamically and algorithmically define our rules. Here are some samples...
  56 </p>
  57 <p>Say I want to dynamically create a rule for:</p>
  58 <pre>
  59 <span class=identifier>    start </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></pre>
  60 <p> I can write it dynamically step-by-step:</p>
  61 <pre> <span class=identifier>   stored_rule</span><span class=special>&lt;&gt;  </span><span class=identifier>start</span><span class=special>;
  62
  63     </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>a</span><span class=special>;
  64     </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>() </span><span class=special>| </span><span class=identifier>b</span><span class=special>;
  65     </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>() </span><span class=special>| </span><span class=identifier>c</span><span class=special>;
  66     </span><span class=identifier>start </span><span class=special>= </span><span class=special>*(</span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>());</span></pre>
  67 <p>Later, I changed my mind and want to redefine it (again dynamically) as:</p>
  68 <pre><span class=identifier>    start </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=special>&gt;&gt; </span><span class=special>(</span><span class=identifier>start </span><span class=special>| </span><span class=identifier>b</span><span class=special>);</span>
  69 </pre>
  70 <p>I write:</p>
  71 <pre> <span class=special>   </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>b</span><span class=special>;
  72     </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>a </span><span class=special>| </span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>();
  73     </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>() </span><span class=special>&gt;&gt; </span><span class=special>(</span><span class=identifier>start </span><span class=special>| </span><span class=identifier>b</span><span class=special>);</span></pre>
  74 <p>Notice the statement:</p>
  75 <pre> <span class=special>   </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>start</span><span class=special>.</span><span class=identifier>copy</span><span class=special>() </span><span class=special>| </span><span class=identifier>b</span><span class=special>;</span></pre>
  76 <p>Why is start.copy() required? Well, because like rules, stored rules are still
  77   embedded by reference when found in the RHS (one reason is to avoid cyclic-shared-pointers).
  78   If we write:</p>
  79 <pre> <span class=special>   </span><span class=identifier>start </span><span class=special>= </span><span class=identifier>start </span><span class=special>| </span><span class=identifier>b</span><span class=special>;</span></pre>
  80 <p>We have <strong>left-recursion</strong>! Copying copy of start avoids self
  81   referencing. What we are doing is making a copy of start, ORing it with b, then
  82   destructively assigning the result back to start.</p>
  83 <table border="0">
  84   <tr>
  85     <td width="10"></td>
  86     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
  87     <td width="30"><a href="stored_rule.html"><img src="theme/l_arr.gif" border="0"></a></td>
  88     <td width="30"><a href="the_lazy_parser.html"><img src="theme/r_arr.gif" border="0"></a></td>
  89   </tr>
  90 </table>
  91 <br>
  92 <hr size="1">
  93 <p class="copyright">Copyright &copy; 1998-2003 Joel de Guzman<br>
  94   <br>
  95   <font size="2">Use, modification and distribution is subject to the Boost Software
  96     License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
  97     http://www.boost.org/LICENSE_1_0.txt)</font></p>
  98 </body>
  99 </html>