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

   1 <html>
   2 <head>
   3 <title>Style Guide</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>Style
  14       Guide </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="portability.html"><img src="theme/l_arr.gif" border="0"></a></td>
  24     <td width="30"><a href="techniques.html"><img src="theme/r_arr.gif" border="0"></a></td>
  25   </tr>
  26 </table>
  27 <p> At some point, especially when there are lots of semantic actions attached
  28   to various points, the grammar tends to be quite difficult to follow. In order
  29   to keep an easy-to-read, consistent en aesthetically pleasing look to the Spirit
  30   code, the following coding styleguide is advised. </p>
  31 <p>This coding style is adapted and extended from the ANTLR/PCCTS style (Terrence
  32   Parr) and <a href="http://groups.yahoo.com/group/boost/files/coding_guidelines.html">Boost
  33   coding guidelines</a> (David Abrahams and Nathan Myers) and is the combined
  34   work of Joel de Guzman, Chris Uzdavinis and Hartmut Kaiser.</p>
  35 <ul>
  36   <li> Rule names use std C++ (Boost) convention. The rule name may be very long.</li>
  37   <li>The '=' is neatly indented 4 spaces below. Like Boost, use spaces instead
  38     of tabs. </li>
  39   <li>Breaking the operands into separate lines puts the semantic actions neatly
  40     to the right. </li>
  41   <li>Semicolon at the last line terminates the rule. </li>
  42   <li>The adjacent parts of a sequence should be indented accordingly to have
  43     all, what belongs to one level, at one indentation level.</li>
  44 </ul>
  45 <pre><span class=identifier>    program
  46         </span><span class=special>=   </span><span class=identifier>program_heading </span><span class=special>[</span><span class=identifier>heading_action</span><span class=special>]
  47     </span><span class=identifier>    </span><span class=special>    &gt;&gt; </span><span class=identifier>block </span><span class=special>[</span><span class=identifier>block_action</span><span class=special>]
  48     </span><span class=identifier>    </span><span class=special>    &gt;&gt; </span><span class=literal>'.'
  49     </span><span class=identifier>    </span><span class=special>|   </span><span class=identifier>another_sequence
  50             </span><span class=special>&gt;&gt; </span><span class=identifier>etc
  51     </span><span class=identifier>    </span><span class=special>;</span></pre>
  52 <ul>
  53   <li>Prefer literals in the grammar instead of identifiers. e.g. <tt>&quot;program&quot;</tt>
  54     instead of <tt>PROGRAM</tt>, <tt>'&gt;='</tt> instead of <tt>GTE</tt> and
  55     <tt>'.' </tt>instead of <tt>DOT</tt>. This makes it much easier to read. If
  56     this isn't possible (for instance where the used tokens must be identified
  57     through integers) capitalized identifiers should be used instead. </li>
  58   <li> Breaking the operands may not be needed for short expressions. e.g. <tt>*(','
  59     &gt;&gt; file_identifier)</tt> as long as the line does not exceed 80 characters.
  60   </li>
  61   <li> If a sequence fits on one line, put spaces inside the parentheses to clearly
  62     separate them from the rules. </li>
  63 </ul>
  64 <pre>    <span class=identifier>program_heading
  65         </span><span class=special>=   </span><span class=identifier>as_lower_d</span><span class=special>[</span><span class=string>&quot;program&quot;</span><span class=special>]
  66             &gt;&gt; </span><span class=identifier>identifier
  67             </span><span class=special>&gt;&gt; </span><span class=literal>'('
  68             </span><span class=special>&gt;&gt; </span><span class=identifier>file_identifier
  69             </span><span class=special>&gt;&gt; *( </span><span class=literal>',' </span><span class=special>&gt;&gt; </span><span class=identifier>file_identifier </span><span class=special>)
  70             &gt;&gt; </span><span class=literal>')'
  71             </span><span class=special>&gt;&gt; </span><span class=literal>';'
  72         </span><span class=special>;</span></pre>
  73 <ul>
  74   <li> Nesting directives: If a rule does not fit on one line (80 characters)
  75     it should be continued on the next line intended by one level. </li>
  76   <li>The brackets of directives, semantic expressions (using Phoenix or LL lambda
  77     expressions) or parsers should be placed as follows. </li>
  78 </ul>
  79 <pre>    <span class=identifier>identifier
  80         </span><span class=special>=   </span><span class=identifier>nocase
  81             </span><span class=special>[
  82                 </span><span class=identifier>lexeme
  83                 </span><span class=special>[
  84                     </span><span class=identifier>alpha </span><span class=special>&gt;&gt; *(</span><span class=identifier>alnum </span><span class=special>| </span><span class=literal>'_'</span><span class=special>) [</span><span class=identifier>id_action</span><span class=special>]
  85                 ]
  86             ]
  87         ;</span></pre>
  88 <ul>
  89   <li> Nesting unary operators (e.g.Kleene star) </li>
  90   <li>Unary rule operators (Kleene star, <tt>'!'</tt>, <tt>'+'</tt> etc.) should
  91     be moved out one space before the corresponding indentation level, if this
  92     rule has a body or a sequence after it, which does not fit on on line. This
  93     makes the formatting more consistent and moves the rule 'body' at the same
  94     indentation level as the rule itself, highlighting the unary operator.</li>
  95 </ul>
  96 <pre><span class=special>    </span><span class=identifier>block
  97         </span><span class=special>=  *(   </span><span class=identifier>label_declaration_part
  98             </span><span class=special>|   </span><span class=identifier>constant_definition_part
  99             </span><span class=special>|   </span><span class=identifier>type_definition_part
 100             </span><span class=special>|   </span><span class=identifier>variable_declaration_part
 101             </span><span class=special>|   </span><span class=identifier>procedure_and_function_declaration_part
 102             </span><span class=special>)
 103             &gt;&gt; </span><span class=identifier>statement_part
 104         </span><span class=special>;</span></pre>
 105 <table border="0">
 106   <tr>
 107     <td width="10"></td>
 108     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
 109     <td width="30"><a href="portability.html"><img src="theme/l_arr.gif" border="0"></a></td>
 110     <td width="30"><a href="techniques.html"><img src="theme/r_arr.gif" border="0"></a></td>
 111   </tr>
 112 </table>
 113 <br>
 114 <hr size="1">
 115 <p class="copyright">Copyright &copy; 2001-2003 Joel de Guzman<br>
 116   Copyright &copy; 2001-2002 Hartmut Kaiser<br>
 117   Copyright &copy; 2001-2002 Chris Uzdavinis<br>
 118   <br>
 119   <font size="2">Use, modification and distribution is subject to the Boost Software
 120     License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 121     http://www.boost.org/LICENSE_1_0.txt)</font></p>
 122 <p class="copyright">&nbsp;</p>
 123 </body>
 124 </html>