1[/==============================================================================
2    Copyright (C) 2001-2011 Joel de Guzman
3    Copyright (C) 2001-2011 Hartmut Kaiser
4
5    Distributed under the Boost Software License, Version 1.0. (See accompanying
6    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7===============================================================================/]
8
9[section Style Guide]
10
11At some point, especially when there are lots of semantic actions attached to
12various points, the grammar tends to be quite difficult to follow. In order to
13keep an easy-to-read, consistent and aesthetically pleasing look to the Spirit
14code, the following coding style guide is advised.
15
16This coding style is adapted and extended from the ANTLR\/PCCTS style and
17[@http://www.boost.org/development/requirements.html Boost Library Requirements
18and Guidelines] and is the combined work of Joel de Guzman, Chris Uzdavinis,
19and Hartmut Kaiser.
20
21* Rule names use std C++ (Boost) convention. The rule name may be very long.
22* The '=' is neatly indented 4 spaces below. Like in Boost, use spaces instead
23  of tabs.
24* Breaking the operands into separate lines puts the semantic actions neatly
25  to the right.
26* Semicolon at the last line terminates the rule.
27* The adjacent parts of a sequence should be indented accordingly to have all,
28  what belongs to one level, at one indentation level.
29
30    program
31        =   program_heading [heading_action]
32            >> block [block_action]
33            >> '.'
34        |   another_sequence
35            >> etc
36        ;
37
38* Prefer literals in the grammar instead of identifiers. e.g. `"program"` instead
39  of `PROGRAM`, `'>='` instead of `GTE` and `'.'` instead of `DOT`. This makes it much
40  easier to read. If this isn't possible (for instance where the used tokens
41  must be identified through integers) capitalized  identifiers should be used
42  instead.
43* Breaking the operands may not be needed for short expressions.
44  e.g. `*(',' >> file_identifier)` as long as the line does not
45  exceed 80   characters.
46* If a sequence fits on one line, put spaces inside the parentheses
47  to clearly separate them from the rules.
48
49    program_heading
50        =   no_case["program"]
51            >> identifier
52            >> '('
53            >> file_identifier
54            >> *( ',' >> file_identifier )
55            >> ')'
56            >> ';'
57        ;
58
59* Nesting directives: If a rule does not fit on one line (80 characters)
60  it should be continued on the next line intended by one level. The brackets
61  of directives, semantic expressions (using Phoenix or LL lambda expressions)
62  or parsers should be placed as follows.
63
64    identifier
65        =   no_case
66            [
67                lexeme
68                [
69                    alpha >> *(alnum | '_') [id_action]
70                ]
71            ]
72       ;
73
74* Nesting unary operators (e.g.Kleene star): Unary rule operators
75  (Kleene star, `'!'`, `'+'` etc.) should be moved out one space before
76  the corresponding indentation level, if this rule has a body or a
77  sequence after it, which does not fit on on line. This makes the
78  formatting more consistent and moves the rule 'body' at the same
79  indentation level as the rule itself, highlighting the unary operator.
80
81    block
82       =  *(   label_declaration_part
83           |   constant_definition_part
84           |   type_definition_part
85           |   variable_declaration_part
86           |   procedure_and_function_declaration_part
87           )
88           >> statement_part
89       ;
90
91[endsect]
92