]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
11 | At some point, especially when there are lots of semantic actions attached to | |
12 | various points, the grammar tends to be quite difficult to follow. In order to | |
13 | keep an easy-to-read, consistent and aesthetically pleasing look to the Spirit | |
14 | code, the following coding style guide is advised. | |
15 | ||
16 | This coding style is adapted and extended from the ANTLR\/PCCTS style and | |
17 | [@http://www.boost.org/development/requirements.html Boost Library Requirements | |
18 | and Guidelines] and is the combined work of Joel de Guzman, Chris Uzdavinis, | |
19 | and 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] |