[/==============================================================================
    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]