ceph/src/boost/libs/spirit/doc/notes/style_guide.qbk

   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]