| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| Distributed under 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) |
| ===============================================================================/] |
| |
| [section Style Guide] |
| |
| 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 and aesthetically pleasing look to the Spirit |
| code, the following coding style guide is advised. |
| |
| This coding style is adapted and extended from the ANTLR\/PCCTS style and |
| [@http://www.boost.org/development/requirements.html Boost Library Requirements |
| and Guidelines] and is the combined work of Joel de Guzman, Chris Uzdavinis, |
| and Hartmut Kaiser. |
| |
| * Rule names use std C++ (Boost) convention. The rule name may be very long. |
| * The '=' is neatly indented 4 spaces below. Like in Boost, use spaces instead |
| of tabs. |
| * Breaking the operands into separate lines puts the semantic actions neatly |
| to the right. |
| * Semicolon at the last line terminates the rule. |
| * The adjacent parts of a sequence should be indented accordingly to have all, |
| what belongs to one level, at one indentation level. |
| |
| program |
| = program_heading [heading_action] |
| >> block [block_action] |
| >> '.' |
| | another_sequence |
| >> etc |
| ; |
| |
| * Prefer literals in the grammar instead of identifiers. e.g. `"program"` instead |
| of `PROGRAM`, `'>='` instead of `GTE` and `'.'` instead of `DOT`. 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. |
| * Breaking the operands may not be needed for short expressions. |
| e.g. `*(',' >> file_identifier)` as long as the line does not |
| exceed 80 characters. |
| * If a sequence fits on one line, put spaces inside the parentheses |
| to clearly separate them from the rules. |
| |
| program_heading |
| = no_case["program"] |
| >> identifier |
| >> '(' |
| >> file_identifier |
| >> *( ',' >> file_identifier ) |
| >> ')' |
| >> ';' |
| ; |
| |
| * 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. The brackets |
| of directives, semantic expressions (using Phoenix or LL lambda expressions) |
| or parsers should be placed as follows. |
| |
| identifier |
| = no_case |
| [ |
| lexeme |
| [ |
| alpha >> *(alnum | '_') [id_action] |
| ] |
| ] |
| ; |
| |
| * Nesting unary operators (e.g.Kleene star): Unary rule operators |
| (Kleene star, `'!'`, `'+'` 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. |
| |
| block |
| = *( label_declaration_part |
| | constant_definition_part |
| | type_definition_part |
| | variable_declaration_part |
| | procedure_and_function_declaration_part |
| ) |
| >> statement_part |
| ; |
| |
| [endsect] |