1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Style Guide</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Spirit 2.5.8"> 8<link rel="up" href="../notes.html" title="Notes"> 9<link rel="prev" href="porting_from_spirit_1_8_x.html" title="Porting from Spirit 1.8.x"> 10<link rel="next" href="../rationale.html" title="Rationale"> 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="porting_from_spirit_1_8_x.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../notes.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="../rationale.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="spirit.notes.style_guide"></a><a class="link" href="style_guide.html" title="Style Guide">Style Guide</a> 28</h3></div></div></div> 29<p> 30 At some point, especially when there are lots of semantic actions attached 31 to various points, the grammar tends to be quite difficult to follow. In 32 order to keep an easy-to-read, consistent and aesthetically pleasing look 33 to the Spirit code, the following coding style guide is advised. 34 </p> 35<p> 36 This coding style is adapted and extended from the ANTLR/PCCTS style and 37 <a href="http://www.boost.org/development/requirements.html" target="_top">Boost Library 38 Requirements and Guidelines</a> and is the combined work of Joel de Guzman, 39 Chris Uzdavinis, and Hartmut Kaiser. 40 </p> 41<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 42<li class="listitem"> 43 Rule names use std C++ (Boost) convention. The rule name may be very 44 long. 45 </li> 46<li class="listitem"> 47 The '=' is neatly indented 4 spaces below. Like in Boost, use spaces 48 instead of tabs. 49 </li> 50<li class="listitem"> 51 Breaking the operands into separate lines puts the semantic actions neatly 52 to the right. 53 </li> 54<li class="listitem"> 55 Semicolon at the last line terminates the rule. 56 </li> 57<li class="listitem"> 58 The adjacent parts of a sequence should be indented accordingly to have 59 all, what belongs to one level, at one indentation level. 60 </li> 61</ul></div> 62<pre class="programlisting"><span class="identifier">program</span> 63 <span class="special">=</span> <span class="identifier">program_heading</span> <span class="special">[</span><span class="identifier">heading_action</span><span class="special">]</span> 64 <span class="special">>></span> <span class="identifier">block</span> <span class="special">[</span><span class="identifier">block_action</span><span class="special">]</span> 65 <span class="special">>></span> <span class="char">'.'</span> 66 <span class="special">|</span> <span class="identifier">another_sequence</span> 67 <span class="special">>></span> <span class="identifier">etc</span> 68 <span class="special">;</span> 69</pre> 70<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 71<li class="listitem"> 72 Prefer literals in the grammar instead of identifiers. e.g. <code class="computeroutput"><span class="string">"program"</span></code> instead of <code class="computeroutput"><span class="identifier">PROGRAM</span></code>, <code class="computeroutput"><span class="char">'>='</span></code> 73 instead of <code class="computeroutput"><span class="identifier">GTE</span></code> and <code class="computeroutput"><span class="char">'.'</span></code> instead of <code class="computeroutput"><span class="identifier">DOT</span></code>. 74 This makes it much easier to read. If this isn't possible (for instance 75 where the used tokens must be identified through integers) capitalized 76 identifiers should be used instead. 77 </li> 78<li class="listitem"> 79 Breaking the operands may not be needed for short expressions. e.g. 80 <code class="computeroutput"><span class="special">*(</span><span class="char">','</span> 81 <span class="special">>></span> <span class="identifier">file_identifier</span><span class="special">)</span></code> as long as the line does not exceed 82 80 characters. 83 </li> 84<li class="listitem"> 85 If a sequence fits on one line, put spaces inside the parentheses to 86 clearly separate them from the rules. 87 </li> 88</ul></div> 89<pre class="programlisting"><span class="identifier">program_heading</span> 90 <span class="special">=</span> <span class="identifier">no_case</span><span class="special">[</span><span class="string">"program"</span><span class="special">]</span> 91 <span class="special">>></span> <span class="identifier">identifier</span> 92 <span class="special">>></span> <span class="char">'('</span> 93 <span class="special">>></span> <span class="identifier">file_identifier</span> 94 <span class="special">>></span> <span class="special">*(</span> <span class="char">','</span> <span class="special">>></span> <span class="identifier">file_identifier</span> <span class="special">)</span> 95 <span class="special">>></span> <span class="char">')'</span> 96 <span class="special">>></span> <span class="char">';'</span> 97 <span class="special">;</span> 98</pre> 99<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 100 Nesting directives: If a rule does not fit on one line (80 characters) 101 it should be continued on the next line intended by one level. The brackets 102 of directives, semantic expressions (using Phoenix or LL lambda expressions) 103 or parsers should be placed as follows. 104 </li></ul></div> 105<pre class="programlisting"><span class="identifier">identifier</span> 106 <span class="special">=</span> <span class="identifier">no_case</span> 107 <span class="special">[</span> 108 <span class="identifier">lexeme</span> 109 <span class="special">[</span> 110 <span class="identifier">alpha</span> <span class="special">>></span> <span class="special">*(</span><span class="identifier">alnum</span> <span class="special">|</span> <span class="char">'_'</span><span class="special">)</span> <span class="special">[</span><span class="identifier">id_action</span><span class="special">]</span> 111 <span class="special">]</span> 112 <span class="special">]</span> 113 <span class="special">;</span> 114</pre> 115<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 116 Nesting unary operators (e.g.Kleene star): Unary rule operators (Kleene 117 star, <code class="computeroutput"><span class="char">'!'</span></code>, <code class="computeroutput"><span class="char">'+'</span></code> 118 etc.) should be moved out one space before the corresponding indentation 119 level, if this rule has a body or a sequence after it, which does not 120 fit on on line. This makes the formatting more consistent and moves the 121 rule 'body' at the same indentation level as the rule itself, highlighting 122 the unary operator. 123 </li></ul></div> 124<pre class="programlisting"><span class="identifier">block</span> 125 <span class="special">=</span> <span class="special">*(</span> <span class="identifier">label_declaration_part</span> 126 <span class="special">|</span> <span class="identifier">constant_definition_part</span> 127 <span class="special">|</span> <span class="identifier">type_definition_part</span> 128 <span class="special">|</span> <span class="identifier">variable_declaration_part</span> 129 <span class="special">|</span> <span class="identifier">procedure_and_function_declaration_part</span> 130 <span class="special">)</span> 131 <span class="special">>></span> <span class="identifier">statement_part</span> 132 <span class="special">;</span> 133</pre> 134</div> 135<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 136<td align="left"></td> 137<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 138 Distributed under the Boost Software License, Version 1.0. (See accompanying 139 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>) 140 </p> 141</div></td> 142</tr></table> 143<hr> 144<div class="spirit-nav"> 145<a accesskey="p" href="porting_from_spirit_1_8_x.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../notes.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="../rationale.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 146</div> 147</body> 148</html> 149
