125 lines
7.2 KiB
HTML
125 lines
7.2 KiB
HTML
<html>
|
|
<head>
|
|
<title>Style Guide</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" href="theme/style.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
<table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2">
|
|
<tr>
|
|
<td width="10">
|
|
</td>
|
|
<td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Style
|
|
Guide </b></font></td>
|
|
<td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" width="112" height="48" align="right" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="portability.html"><img src="theme/l_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="techniques.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<p> At some point, especially when there are lots of semantic actions attached
|
|
to various points, the grammar tends to be quite difficult to follow. In order
|
|
to keep an easy-to-read, consistent en aesthetically pleasing look to the Spirit
|
|
code, the following coding styleguide is advised. </p>
|
|
<p>This coding style is adapted and extended from the ANTLR/PCCTS style (Terrence
|
|
Parr) and <a href="http://groups.yahoo.com/group/boost/files/coding_guidelines.html">Boost
|
|
coding guidelines</a> (David Abrahams and Nathan Myers) and is the combined
|
|
work of Joel de Guzman, Chris Uzdavinis and Hartmut Kaiser.</p>
|
|
<ul>
|
|
<li> Rule names use std C++ (Boost) convention. The rule name may be very long.</li>
|
|
<li>The '=' is neatly indented 4 spaces below. Like Boost, use spaces instead
|
|
of tabs. </li>
|
|
<li>Breaking the operands into separate lines puts the semantic actions neatly
|
|
to the right. </li>
|
|
<li>Semicolon at the last line terminates the rule. </li>
|
|
<li>The adjacent parts of a sequence should be indented accordingly to have
|
|
all, what belongs to one level, at one indentation level.</li>
|
|
</ul>
|
|
<pre><span class=identifier> program
|
|
</span><span class=special>= </span><span class=identifier>program_heading </span><span class=special>[</span><span class=identifier>heading_action</span><span class=special>]
|
|
</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>]
|
|
</span><span class=identifier> </span><span class=special> >> </span><span class=literal>'.'
|
|
</span><span class=identifier> </span><span class=special>| </span><span class=identifier>another_sequence
|
|
</span><span class=special>>> </span><span class=identifier>etc
|
|
</span><span class=identifier> </span><span class=special>;</span></pre>
|
|
<ul>
|
|
<li>Prefer literals in the grammar instead of identifiers. e.g. <tt>"program"</tt>
|
|
instead of <tt>PROGRAM</tt>, <tt>'>='</tt> instead of <tt>GTE</tt> and
|
|
<tt>'.' </tt>instead of <tt>DOT</tt>. This makes it much easier to read. If
|
|
this isn't possible (for instance where the used tokens must be identified
|
|
through integers) capitalized identifiers should be used instead. </li>
|
|
<li> Breaking the operands may not be needed for short expressions. e.g. <tt>*(','
|
|
>> file_identifier)</tt> as long as the line does not exceed 80 characters.
|
|
</li>
|
|
<li> If a sequence fits on one line, put spaces inside the parentheses to clearly
|
|
separate them from the rules. </li>
|
|
</ul>
|
|
<pre> <span class=identifier>program_heading
|
|
</span><span class=special>= </span><span class=identifier>as_lower_d</span><span class=special>[</span><span class=string>"program"</span><span class=special>]
|
|
>> </span><span class=identifier>identifier
|
|
</span><span class=special>>> </span><span class=literal>'('
|
|
</span><span class=special>>> </span><span class=identifier>file_identifier
|
|
</span><span class=special>>> *( </span><span class=literal>',' </span><span class=special>>> </span><span class=identifier>file_identifier </span><span class=special>)
|
|
>> </span><span class=literal>')'
|
|
</span><span class=special>>> </span><span class=literal>';'
|
|
</span><span class=special>;</span></pre>
|
|
<ul>
|
|
<li> Nesting directives: If a rule does not fit on one line (80 characters)
|
|
it should be continued on the next line intended by one level. </li>
|
|
<li>The brackets of directives, semantic expressions (using Phoenix or LL lambda
|
|
expressions) or parsers should be placed as follows. </li>
|
|
</ul>
|
|
<pre> <span class=identifier>identifier
|
|
</span><span class=special>= </span><span class=identifier>nocase
|
|
</span><span class=special>[
|
|
</span><span class=identifier>lexeme
|
|
</span><span class=special>[
|
|
</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>]
|
|
]
|
|
]
|
|
;</span></pre>
|
|
<ul>
|
|
<li> Nesting unary operators (e.g.Kleene star) </li>
|
|
<li>Unary rule operators (Kleene star, <tt>'!'</tt>, <tt>'+'</tt> etc.) should
|
|
be moved out one space before the corresponding indentation level, if this
|
|
rule has a body or a sequence after it, which does not fit on on line. This
|
|
makes the formatting more consistent and moves the rule 'body' at the same
|
|
indentation level as the rule itself, highlighting the unary operator.</li>
|
|
</ul>
|
|
<pre><span class=special> </span><span class=identifier>block
|
|
</span><span class=special>= *( </span><span class=identifier>label_declaration_part
|
|
</span><span class=special>| </span><span class=identifier>constant_definition_part
|
|
</span><span class=special>| </span><span class=identifier>type_definition_part
|
|
</span><span class=special>| </span><span class=identifier>variable_declaration_part
|
|
</span><span class=special>| </span><span class=identifier>procedure_and_function_declaration_part
|
|
</span><span class=special>)
|
|
>> </span><span class=identifier>statement_part
|
|
</span><span class=special>;</span></pre>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="portability.html"><img src="theme/l_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="techniques.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<hr size="1">
|
|
<p class="copyright">Copyright © 2001-2003 Joel de Guzman<br>
|
|
Copyright © 2001-2002 Hartmut Kaiser<br>
|
|
Copyright © 2001-2002 Chris Uzdavinis<br>
|
|
<br>
|
|
<font size="2">Use, modification and distribution is subject to the Boost Software
|
|
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt)</font></p>
|
|
<p class="copyright"> </p>
|
|
</body>
|
|
</html>
|