.clang-format

   1 # DO NOT COMMIT OR MERGE CODE THAT IS RUN THROUGH THIS TOOL YET.
   2 #
   3 # WE ARE STILL DISCUSSING OUR DESIRED STYLE AND ITERATING ON IT.
   4 #     (12 Feb 2020)
   5
   6 ---
   7 Language:        Cpp
   8 # Out of all supported styles, LLVM seems closest to our own.
   9 BasedOnStyle:    LLVM
  10
  11 ################
  12 #
  13 # Deviations from LLVM's style.
  14 #
  15 ################
  16
  17 # We prefer an indentation width of 4 columns; LLVM likes 2.
  18 ## OVERRIDE FOR COMPARISON
  19 IndentWidth:     2
  20
  21 ## OVERRIDE FOR COMPARISON
  22 ## for now i'm not sorting includes, since that makes every file get touched.
  23 SortIncludes: false
  24
  25 # We prefer 79; llvm likes 80.
  26 ColumnLimit: 79
  27
  28 # Where do we want to put backslashes on multiline macros?  Our choices are
  29 # "as far left as possible", "as far right as possible", and "make no changes."
  30 # LLVM defaults to right, but we don't dig that.
  31 AlignEscapedNewlines: Left
  32
  33 # When we see a bunch of things in a row with comments after them, should we
  34 # try to align those comments?  Doing so makes some of our code pretty ugly.
  35 AlignTrailingComments: false
  36
  37 # We use a function declaration style much closer to BSD KNF than to LLVM's.
  38 # We say:
  39 #      int foo(int x);
  40 #      int
  41 #      foo(int x)
  42 #      {
  43 #          ...
  44 #      }
  45 # whereas llvm prefers:
  46 #      int foo(int x);
  47 #      int foo(int x) {
  48 #          ...
  49 #      }
  50 # or even:
  51 #      int foo(int x) { ... }
  52 #
  53 BreakBeforeBraces: Custom
  54 BraceWrapping:
  55   AfterFunction:   true
  56 AllowShortFunctionsOnASingleLine: None
  57 AlwaysBreakAfterReturnType: AllDefinitions
  58
  59 # We don't like blocks to start with an empty line.
  60 #
  61 KeepEmptyLinesAtTheStartOfBlocks: false
  62
  63 ################
  64 #
  65 # Tor-specific magic
  66 #
  67 ################
  68
  69 #
  70 # These comments are magical, and should not be changed.
  71 #
  72 CommentPragmas:  'LCOV_EXCL|COVERITY'
  73
  74 #
  75 # Remove duplicate empty lines.
  76 #
  77 MaxEmptyLinesToKeep: 1
  78
  79 #
  80 # Indent preprocessor directives, for clarity.
  81 #
  82 IndentPPDirectives: AfterHash
  83
  84 #
  85 # These introduce an iteration, and work a bit like a for loop.
  86 #
  87 # Note that we can NOT include ones that don't work like "for".  For example,
  88 # if the body is an argument to the macro, we can't list it here.
  89 #
  90 ForEachMacros:
  91   - MAP_FOREACH
  92   - MAP_FOREACH_MODIFY
  93   - TOR_SIMPLEQ_FOREACH
  94   - TOR_SIMPLEQ_FOREACH_SAFE
  95   - TOR_SLIST_FOREACH
  96   - TOR_SLIST_FOREACH_SAFE
  97   - TOR_LIST_FOREACH
  98   - TOR_LIST_FOREACH_SAFE
  99   - TOR_TAILQ_FOREACH
 100   - TOR_TAILQ_FOREACH_SAFE
 101   - TOR_TAILQ_FOREACH_REVERSE
 102   - TOR_TAILQ_FOREACH_REVERSE_SAFE
 103   - TOR_CIRCLEQ_FOREACH
 104   - TOR_CIRCLEQ_FOREACH_SAFE
 105   - TOR_CIRCLEQ_FOREACH_REVERSE
 106   - TOR_CIRCLEQ_FOREACH_REVERSE_SAFE
 107   - HT_FOREACH
 108   - SMARTLIST_FOREACH_BEGIN
 109   - DIGESTMAP_FOREACH
 110   - DIGESTMAP_FOREACH_MODIFY
 111   - DIGEST256MAP_FOREACH
 112   - DIGEST256MAP_FOREACH_MODIFY
 113   - SDMAP_FOREACH
 114   - RIMAP_FOREACH
 115   - EIMAP_FOREACH
 116
 117 #
 118 # Omitting:
 119 #
 120 # - SMARTLIST_FOREACH, since the body of the loop is an argument.
 121
 122 #
 123 # This explains how to sort our headers.
 124 #
 125 # This is more complex than it truly should be, but I've edited this till
 126 # compilation still mostly passes.
 127 #
 128 # I'm disabling this, however, since it's a distraction from the other
 129 # formatting issues. See SortIncludes above.
 130 #
 131 IncludeCategories:
 132   - Regex:           '^"orconfig.h'
 133     Priority:        -30
 134   - Regex:           '^"ext/'
 135     Priority:        -18
 136   - Regex:           '^"lib/'
 137     Priority:        -10
 138   - Regex:           '^"core/or/or.h'
 139     Priority:        -5
 140   - Regex:           '^"core/'
 141     Priority:        5
 142   - Regex:           '^"feature/'
 143     Priority:        10
 144   - Regex:           '^"app/'
 145     Priority:        20
 146
 147 #
 148 # These macros should always cause indentation, as though they were { and }.
 149 #
 150 # Do NOT put macros here unless you want an extra level of indentation between
 151 # them whenever they appear.
 152 #
 153 MacroBlockBegin: "^STMT_BEGIN|TT_STMT_BEGIN$"
 154 MacroBlockEnd:   "^STMT_END|TT_STMT_END$"
 155
 156 #
 157 # These macros are interpreted as types.
 158 # (Not supported in my clang-format)
 159 #
 160 # TypenameMacros:
 161 #    - "STACK_OF"
 162
 163 ...