| 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> >> </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> >> </span><span class=literal>'.' |
|---|
| 49 | </span><span class=identifier> </span><span class=special>| </span><span class=identifier>another_sequence |
|---|
| 50 | </span><span class=special>>> </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>"program"</tt> |
|---|
| 54 | instead of <tt>PROGRAM</tt>, <tt>'>='</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 | >> 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>"program"</span><span class=special>] |
|---|
| 66 | >> </span><span class=identifier>identifier |
|---|
| 67 | </span><span class=special>>> </span><span class=literal>'(' |
|---|
| 68 | </span><span class=special>>> </span><span class=identifier>file_identifier |
|---|
| 69 | </span><span class=special>>> *( </span><span class=literal>',' </span><span class=special>>> </span><span class=identifier>file_identifier </span><span class=special>) |
|---|
| 70 | >> </span><span class=literal>')' |
|---|
| 71 | </span><span class=special>>> </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>>> *(</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 | >> </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 © 2001-2003 Joel de Guzman<br> |
|---|
| 116 | Copyright © 2001-2002 Hartmut Kaiser<br> |
|---|
| 117 | Copyright © 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"> </p> |
|---|
| 123 | </body> |
|---|
| 124 | </html> |
|---|
