Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 1 | ========================== |
| 2 | Clang-Format Style Options |
| 3 | ========================== |
| 4 | |
| 5 | :doc:`ClangFormatStyleOptions` describes configurable formatting style options |
| 6 | supported by :doc:`LibFormat` and :doc:`ClangFormat`. |
| 7 | |
| 8 | When using :program:`clang-format` command line utility or |
| 9 | ``clang::format::reformat(...)`` functions from code, one can either use one of |
| 10 | the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a |
| 11 | custom style by configuring specific style options. |
| 12 | |
| 13 | |
| 14 | Configuring Style with clang-format |
| 15 | =================================== |
| 16 | |
| 17 | :program:`clang-format` supports two ways to provide custom style options: |
| 18 | directly specify style configuration in the ``-style=`` command line option or |
Hans Wennborg | 9a7a50e | 2013-09-10 15:41:12 +0000 | [diff] [blame] | 19 | use ``-style=file`` and put style configuration in the ``.clang-format`` or |
| 20 | ``_clang-format`` file in the project directory. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 21 | |
| 22 | When using ``-style=file``, :program:`clang-format` for each input file will |
| 23 | try to find the ``.clang-format`` file located in the closest parent directory |
| 24 | of the input file. When the standard input is used, the search is started from |
| 25 | the current directory. |
| 26 | |
| 27 | The ``.clang-format`` file uses YAML format: |
| 28 | |
| 29 | .. code-block:: yaml |
| 30 | |
| 31 | key1: value1 |
| 32 | key2: value2 |
| 33 | # A comment. |
| 34 | ... |
| 35 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 36 | The configuration file can consist of several sections each having different |
| 37 | ``Language:`` parameter denoting the programming language this section of the |
| 38 | configuration is targeted at. See the description of the **Language** option |
| 39 | below for the list of supported languages. The first section may have no |
| 40 | language set, it will set the default style options for all lanugages. |
| 41 | Configuration sections for specific language will override options set in the |
| 42 | default section. |
| 43 | |
| 44 | When :program:`clang-format` formats a file, it auto-detects the language using |
| 45 | the file name. When formatting standard input or a file that doesn't have the |
| 46 | extension corresponding to its language, ``-assume-filename=`` option can be |
| 47 | used to override the file name :program:`clang-format` uses to detect the |
| 48 | language. |
| 49 | |
| 50 | An example of a configuration file for multiple languages: |
| 51 | |
| 52 | .. code-block:: yaml |
| 53 | |
| 54 | --- |
| 55 | # We'll use defaults from the LLVM style, but with 4 columns indentation. |
| 56 | BasedOnStyle: LLVM |
| 57 | IndentWidth: 4 |
| 58 | --- |
| 59 | Language: Cpp |
| 60 | # Force pointers to the type for C++. |
| 61 | DerivePointerAlignment: false |
| 62 | PointerAlignment: Left |
| 63 | --- |
| 64 | Language: JavaScript |
| 65 | # Use 100 columns for JS. |
| 66 | ColumnLimit: 100 |
| 67 | --- |
| 68 | Language: Proto |
| 69 | # Don't format .proto files. |
| 70 | DisableFormat: true |
| 71 | ... |
| 72 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 73 | An easy way to get a valid ``.clang-format`` file containing all configuration |
| 74 | options of a certain predefined style is: |
| 75 | |
| 76 | .. code-block:: console |
| 77 | |
| 78 | clang-format -style=llvm -dump-config > .clang-format |
| 79 | |
| 80 | When specifying configuration in the ``-style=`` option, the same configuration |
| 81 | is applied for all input files. The format of the configuration is: |
| 82 | |
| 83 | .. code-block:: console |
| 84 | |
| 85 | -style='{key1: value1, key2: value2, ...}' |
| 86 | |
| 87 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 88 | Disabling Formatting on a Piece of Code |
| 89 | ======================================= |
| 90 | |
| 91 | Clang-format understands also special comments that switch formatting in a |
| 92 | delimited range. The code between a comment ``// clang-format off`` or |
| 93 | ``/* clang-format off */`` up to a comment ``// clang-format on`` or |
| 94 | ``/* clang-format on */`` will not be formatted. The comments themselves |
| 95 | will be formatted (aligned) normally. |
| 96 | |
| 97 | .. code-block:: c++ |
| 98 | |
| 99 | int formatted_code; |
| 100 | // clang-format off |
| 101 | void unformatted_code ; |
| 102 | // clang-format on |
| 103 | void formatted_code_again; |
| 104 | |
| 105 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 106 | Configuring Style in Code |
| 107 | ========================= |
| 108 | |
| 109 | When using ``clang::format::reformat(...)`` functions, the format is specified |
| 110 | by supplying the `clang::format::FormatStyle |
| 111 | <http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_ |
| 112 | structure. |
| 113 | |
| 114 | |
| 115 | Configurable Format Style Options |
| 116 | ================================= |
| 117 | |
| 118 | This section lists the supported style options. Value type is specified for |
| 119 | each option. For enumeration types possible values are specified both as a C++ |
Alexander Kornienko | c4f73e0 | 2013-09-04 15:14:18 +0000 | [diff] [blame] | 120 | enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in |
| 121 | the configuration (without a prefix: ``Auto``). |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 122 | |
| 123 | |
| 124 | **BasedOnStyle** (``string``) |
| 125 | The style used for all options not specifically set in the configuration. |
| 126 | |
| 127 | This option is supported only in the :program:`clang-format` configuration |
| 128 | (both within ``-style='{...}'`` and the ``.clang-format`` file). |
| 129 | |
| 130 | Possible values: |
| 131 | |
| 132 | * ``LLVM`` |
| 133 | A style complying with the `LLVM coding standards |
| 134 | <http://llvm.org/docs/CodingStandards.html>`_ |
| 135 | * ``Google`` |
| 136 | A style complying with `Google's C++ style guide |
| 137 | <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_ |
| 138 | * ``Chromium`` |
| 139 | A style complying with `Chromium's style guide |
| 140 | <http://www.chromium.org/developers/coding-style>`_ |
| 141 | * ``Mozilla`` |
| 142 | A style complying with `Mozilla's style guide |
| 143 | <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_ |
| 144 | * ``WebKit`` |
| 145 | A style complying with `WebKit's style guide |
| 146 | <http://www.webkit.org/coding/coding-style.html>`_ |
| 147 | |
| 148 | .. START_FORMAT_STYLE_OPTIONS |
| 149 | |
| 150 | **AccessModifierOffset** (``int``) |
| 151 | The extra indent or outdent of access modifiers, e.g. ``public:``. |
| 152 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame^] | 153 | **AlignAfterOpenBracket** (``bool``) |
| 154 | If ``true``, horizontally aligns arguments after an open bracket. |
| 155 | |
| 156 | This applies to round brackets (parentheses), angle brackets and square |
| 157 | brackets. This will result in formattings like |
| 158 | \code |
| 159 | someLongFunction(argument1, |
| 160 | argument2); |
| 161 | \endcode |
| 162 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 163 | **AlignEscapedNewlinesLeft** (``bool``) |
| 164 | If ``true``, aligns escaped newlines as far left as possible. |
| 165 | Otherwise puts them into the right-most column. |
| 166 | |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame^] | 167 | **AlignOperands** (``bool``) |
| 168 | If ``true``, horizontally align operands of binary and ternary |
| 169 | expressions. |
| 170 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 171 | **AlignTrailingComments** (``bool``) |
| 172 | If ``true``, aligns trailing comments. |
| 173 | |
| 174 | **AllowAllParametersOfDeclarationOnNextLine** (``bool``) |
| 175 | Allow putting all parameters of a function declaration onto |
| 176 | the next line even if ``BinPackParameters`` is ``false``. |
| 177 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 178 | **AllowShortBlocksOnASingleLine** (``bool``) |
| 179 | Allows contracting simple braced statements to a single line. |
| 180 | |
| 181 | E.g., this allows ``if (a) { return; }`` to be put on a single line. |
| 182 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 183 | **AllowShortCaseLabelsOnASingleLine** (``bool``) |
| 184 | If ``true``, short case labels will be contracted to a single line. |
| 185 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 186 | **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) |
| 187 | Dependent on the value, ``int f() { return 0; }`` can be put |
| 188 | on a single line. |
| 189 | |
| 190 | Possible values: |
| 191 | |
| 192 | * ``SFS_None`` (in configuration: ``None``) |
| 193 | Never merge functions into a single line. |
| 194 | * ``SFS_Inline`` (in configuration: ``Inline``) |
| 195 | Only merge functions defined inside a class. |
Stephen Hines | 0e2c34f | 2015-03-23 12:09:02 -0700 | [diff] [blame^] | 196 | * ``SFS_Empty`` (in configuration: ``Empty``) |
| 197 | Only merge empty functions. |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 198 | * ``SFS_All`` (in configuration: ``All``) |
| 199 | Merge all functions fitting on a single line. |
| 200 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 201 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 202 | **AllowShortIfStatementsOnASingleLine** (``bool``) |
| 203 | If ``true``, ``if (a) return;`` can be put on a single |
| 204 | line. |
| 205 | |
| 206 | **AllowShortLoopsOnASingleLine** (``bool``) |
| 207 | If ``true``, ``while (true) continue;`` can be put on a |
| 208 | single line. |
| 209 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 210 | **AlwaysBreakAfterDefinitionReturnType** (``bool``) |
| 211 | If ``true``, always break after function definition return types. |
| 212 | |
| 213 | More truthfully called 'break before the identifier following the type |
| 214 | in a function definition'. PenaltyReturnTypeOnItsOwnLine becomes |
| 215 | irrelevant. |
| 216 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 217 | **AlwaysBreakBeforeMultilineStrings** (``bool``) |
| 218 | If ``true``, always break before multiline string literals. |
| 219 | |
| 220 | **AlwaysBreakTemplateDeclarations** (``bool``) |
| 221 | If ``true``, always break after the ``template<...>`` of a |
| 222 | template declaration. |
| 223 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 224 | **BinPackArguments** (``bool``) |
| 225 | If ``false``, a function call's arguments will either be all on the |
| 226 | same line or will have one line each. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 227 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 228 | **BinPackParameters** (``bool``) |
| 229 | If ``false``, a function declaration's or function definition's |
| 230 | parameters will either all be on the same line or will have one line each. |
| 231 | |
| 232 | **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) |
| 233 | The way to wrap binary operators. |
| 234 | |
| 235 | Possible values: |
| 236 | |
| 237 | * ``BOS_None`` (in configuration: ``None``) |
| 238 | Break after operators. |
| 239 | * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) |
| 240 | Break before operators that aren't assignments. |
| 241 | * ``BOS_All`` (in configuration: ``All``) |
| 242 | Break before operators. |
| 243 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 244 | |
| 245 | **BreakBeforeBraces** (``BraceBreakingStyle``) |
| 246 | The brace breaking style to use. |
| 247 | |
| 248 | Possible values: |
| 249 | |
| 250 | * ``BS_Attach`` (in configuration: ``Attach``) |
| 251 | Always attach braces to surrounding context. |
| 252 | * ``BS_Linux`` (in configuration: ``Linux``) |
| 253 | Like ``Attach``, but break before braces on function, namespace and |
| 254 | class definitions. |
| 255 | * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 256 | Like ``Attach``, but break before function definitions, and 'else'. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 257 | * ``BS_Allman`` (in configuration: ``Allman``) |
| 258 | Always break before braces. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 259 | * ``BS_GNU`` (in configuration: ``GNU``) |
| 260 | Always break before braces and add an extra level of indentation to |
| 261 | braces of control statements, not to those of class, function |
| 262 | or other definitions. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 263 | |
| 264 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 265 | **BreakBeforeTernaryOperators** (``bool``) |
| 266 | If ``true``, ternary operators will be placed after line breaks. |
| 267 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 268 | **BreakConstructorInitializersBeforeComma** (``bool``) |
| 269 | Always break constructor initializers before commas and align |
| 270 | the commas with the colon. |
| 271 | |
| 272 | **ColumnLimit** (``unsigned``) |
| 273 | The column limit. |
| 274 | |
| 275 | A column limit of ``0`` means that there is no column limit. In this case, |
| 276 | clang-format will respect the input's line breaking decisions within |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 277 | statements unless they contradict other rules. |
| 278 | |
| 279 | **CommentPragmas** (``std::string``) |
| 280 | A regular expression that describes comments with special meaning, |
| 281 | which should not be split into lines or otherwise changed. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 282 | |
| 283 | **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) |
| 284 | If the constructor initializers don't fit on a line, put each |
| 285 | initializer on its own line. |
| 286 | |
| 287 | **ConstructorInitializerIndentWidth** (``unsigned``) |
| 288 | The number of characters to use for indentation of constructor |
| 289 | initializer lists. |
| 290 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 291 | **ContinuationIndentWidth** (``unsigned``) |
| 292 | Indent width for line continuations. |
| 293 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 294 | **Cpp11BracedListStyle** (``bool``) |
| 295 | If ``true``, format braced lists as best suited for C++11 braced |
| 296 | lists. |
| 297 | |
| 298 | Important differences: |
| 299 | - No spaces inside the braced list. |
| 300 | - No line break before the closing brace. |
| 301 | - Indentation with the continuation indent, not with the block indent. |
| 302 | |
| 303 | Fundamentally, C++11 braced lists are formatted exactly like function |
| 304 | calls would be formatted in their place. If the braced list follows a name |
| 305 | (e.g. a type or variable name), clang-format formats as if the ``{}`` were |
| 306 | the parentheses of a function call with that name. If there is no name, |
| 307 | a zero-length name is assumed. |
| 308 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 309 | **DerivePointerAlignment** (``bool``) |
| 310 | If ``true``, analyze the formatted file for the most common |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 311 | alignment of & and \*. ``PointerAlignment`` is then used only as fallback. |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 312 | |
| 313 | **DisableFormat** (``bool``) |
| 314 | Disables formatting at all. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 315 | |
| 316 | **ExperimentalAutoDetectBinPacking** (``bool``) |
| 317 | If ``true``, clang-format detects whether function calls and |
| 318 | definitions are formatted with one parameter per line. |
| 319 | |
| 320 | Each call can be bin-packed, one-per-line or inconclusive. If it is |
| 321 | inconclusive, e.g. completely on one line, but a decision needs to be |
| 322 | made, clang-format analyzes whether there are other bin-packed cases in |
| 323 | the input file and act accordingly. |
| 324 | |
| 325 | NOTE: This is an experimental flag, that might go away or be renamed. Do |
| 326 | not use this in config files, etc. Use at your own risk. |
| 327 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 328 | **ForEachMacros** (``std::vector<std::string>``) |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 329 | A vector of macros that should be interpreted as foreach loops |
| 330 | instead of as function calls. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 331 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 332 | These are expected to be macros of the form: |
| 333 | \code |
| 334 | FOREACH(<variable-declaration>, ...) |
| 335 | <loop-body> |
| 336 | \endcode |
| 337 | |
| 338 | For example: BOOST_FOREACH. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 339 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 340 | **IndentCaseLabels** (``bool``) |
| 341 | Indent case labels one level from the switch statement. |
| 342 | |
| 343 | When ``false``, use the same indentation level as for the switch statement. |
| 344 | Switch statement body is always indented one level more than case labels. |
| 345 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 346 | **IndentWidth** (``unsigned``) |
Alexander Kornienko | f6a6882 | 2013-09-27 16:16:55 +0000 | [diff] [blame] | 347 | The number of columns to use for indentation. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 348 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 349 | **IndentWrappedFunctionNames** (``bool``) |
| 350 | Indent if a function definition or declaration is wrapped after the |
| 351 | type. |
| 352 | |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 353 | **KeepEmptyLinesAtTheStartOfBlocks** (``bool``) |
| 354 | If true, empty lines at the start of blocks are kept. |
| 355 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 356 | **Language** (``LanguageKind``) |
| 357 | Language, this format style is targeted at. |
| 358 | |
| 359 | Possible values: |
| 360 | |
| 361 | * ``LK_None`` (in configuration: ``None``) |
| 362 | Do not use. |
| 363 | * ``LK_Cpp`` (in configuration: ``Cpp``) |
| 364 | Should be used for C, C++, ObjectiveC, ObjectiveC++. |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 365 | * ``LK_Java`` (in configuration: ``Java``) |
| 366 | Should be used for Java. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 367 | * ``LK_JavaScript`` (in configuration: ``JavaScript``) |
| 368 | Should be used for JavaScript. |
| 369 | * ``LK_Proto`` (in configuration: ``Proto``) |
| 370 | Should be used for Protocol Buffers |
| 371 | (https://developers.google.com/protocol-buffers/). |
| 372 | |
| 373 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 374 | **MaxEmptyLinesToKeep** (``unsigned``) |
| 375 | The maximum number of consecutive empty lines to keep. |
| 376 | |
| 377 | **NamespaceIndentation** (``NamespaceIndentationKind``) |
| 378 | The indentation used for namespaces. |
| 379 | |
| 380 | Possible values: |
| 381 | |
| 382 | * ``NI_None`` (in configuration: ``None``) |
| 383 | Don't indent in namespaces. |
| 384 | * ``NI_Inner`` (in configuration: ``Inner``) |
| 385 | Indent only in inner namespaces (nested in other namespaces). |
| 386 | * ``NI_All`` (in configuration: ``All``) |
| 387 | Indent in all namespaces. |
| 388 | |
| 389 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 390 | **ObjCBlockIndentWidth** (``unsigned``) |
| 391 | The number of characters to use for indentation of ObjC blocks. |
| 392 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 393 | **ObjCSpaceAfterProperty** (``bool``) |
| 394 | Add a space after ``@property`` in Objective-C, i.e. use |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 395 | ``\@property (readonly)`` instead of ``\@property(readonly)``. |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 396 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 397 | **ObjCSpaceBeforeProtocolList** (``bool``) |
| 398 | Add a space in front of an Objective-C protocol list, i.e. use |
| 399 | ``Foo <Protocol>`` instead of ``Foo<Protocol>``. |
| 400 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 401 | **PenaltyBreakBeforeFirstCallParameter** (``unsigned``) |
| 402 | The penalty for breaking a function call after "call(". |
| 403 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 404 | **PenaltyBreakComment** (``unsigned``) |
| 405 | The penalty for each line break introduced inside a comment. |
| 406 | |
| 407 | **PenaltyBreakFirstLessLess** (``unsigned``) |
| 408 | The penalty for breaking before the first ``<<``. |
| 409 | |
| 410 | **PenaltyBreakString** (``unsigned``) |
| 411 | The penalty for each line break introduced inside a string literal. |
| 412 | |
| 413 | **PenaltyExcessCharacter** (``unsigned``) |
| 414 | The penalty for each character outside of the column limit. |
| 415 | |
| 416 | **PenaltyReturnTypeOnItsOwnLine** (``unsigned``) |
| 417 | Penalty for putting the return type of a function onto its own |
| 418 | line. |
| 419 | |
Stephen Hines | c568f1e | 2014-07-21 00:47:37 -0700 | [diff] [blame] | 420 | **PointerAlignment** (``PointerAlignmentStyle``) |
| 421 | Pointer and reference alignment style. |
| 422 | |
| 423 | Possible values: |
| 424 | |
| 425 | * ``PAS_Left`` (in configuration: ``Left``) |
| 426 | Align pointer to the left. |
| 427 | * ``PAS_Right`` (in configuration: ``Right``) |
| 428 | Align pointer to the right. |
| 429 | * ``PAS_Middle`` (in configuration: ``Middle``) |
| 430 | Align pointer in the middle. |
| 431 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 432 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 433 | **SpaceAfterCStyleCast** (``bool``) |
| 434 | If ``true``, a space may be inserted after C style casts. |
| 435 | |
Daniel Jasper | 9b4de85 | 2013-09-25 15:15:02 +0000 | [diff] [blame] | 436 | **SpaceBeforeAssignmentOperators** (``bool``) |
Alexander Kornienko | f6a6882 | 2013-09-27 16:16:55 +0000 | [diff] [blame] | 437 | If ``false``, spaces will be removed before assignment operators. |
Daniel Jasper | 9b4de85 | 2013-09-25 15:15:02 +0000 | [diff] [blame] | 438 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 439 | **SpaceBeforeParens** (``SpaceBeforeParensOptions``) |
| 440 | Defines in which cases to put a space before opening parentheses. |
| 441 | |
| 442 | Possible values: |
| 443 | |
| 444 | * ``SBPO_Never`` (in configuration: ``Never``) |
| 445 | Never put a space before opening parentheses. |
| 446 | * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) |
| 447 | Put a space before opening parentheses only after control statement |
| 448 | keywords (``for/if/while...``). |
| 449 | * ``SBPO_Always`` (in configuration: ``Always``) |
| 450 | Always put a space before opening parentheses, except when it's |
| 451 | prohibited by the syntax rules (in function-like macro definitions) or |
| 452 | when determined by other style rules (after unary operators, opening |
| 453 | parentheses, etc.) |
| 454 | |
| 455 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 456 | **SpaceInEmptyParentheses** (``bool``) |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 457 | If ``true``, spaces may be inserted into '()'. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 458 | |
| 459 | **SpacesBeforeTrailingComments** (``unsigned``) |
Stephen Hines | 6bcf27b | 2014-05-29 04:14:42 -0700 | [diff] [blame] | 460 | The number of spaces before trailing line comments |
| 461 | (``//`` - comments). |
| 462 | |
| 463 | This does not affect trailing block comments (``/**/`` - comments) as those |
| 464 | commonly have different usage patterns and a number of special cases. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 465 | |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 466 | **SpacesInAngles** (``bool``) |
| 467 | If ``true``, spaces will be inserted after '<' and before '>' in |
| 468 | template argument lists |
| 469 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 470 | **SpacesInCStyleCastParentheses** (``bool``) |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 471 | If ``true``, spaces may be inserted into C style casts. |
| 472 | |
| 473 | **SpacesInContainerLiterals** (``bool``) |
| 474 | If ``true``, spaces are inserted inside container literals (e.g. |
| 475 | ObjC and Javascript array and dict literals). |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 476 | |
| 477 | **SpacesInParentheses** (``bool``) |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 478 | If ``true``, spaces will be inserted after '(' and before ')'. |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 479 | |
Stephen Hines | 176edba | 2014-12-01 14:53:08 -0800 | [diff] [blame] | 480 | **SpacesInSquareBrackets** (``bool``) |
| 481 | If ``true``, spaces will be inserted after '[' and before ']'. |
| 482 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 483 | **Standard** (``LanguageStandard``) |
| 484 | Format compatible with this standard, e.g. use |
| 485 | ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03. |
| 486 | |
| 487 | Possible values: |
| 488 | |
| 489 | * ``LS_Cpp03`` (in configuration: ``Cpp03``) |
| 490 | Use C++03-compatible syntax. |
| 491 | * ``LS_Cpp11`` (in configuration: ``Cpp11``) |
| 492 | Use features of C++11 (e.g. ``A<A<int>>`` instead of |
| 493 | ``A<A<int> >``). |
| 494 | * ``LS_Auto`` (in configuration: ``Auto``) |
| 495 | Automatic detection based on the input. |
| 496 | |
| 497 | |
Alexander Kornienko | f6a6882 | 2013-09-27 16:16:55 +0000 | [diff] [blame] | 498 | **TabWidth** (``unsigned``) |
| 499 | The number of columns used for tab stops. |
| 500 | |
| 501 | **UseTab** (``UseTabStyle``) |
| 502 | The way to use tab characters in the resulting file. |
| 503 | |
| 504 | Possible values: |
| 505 | |
| 506 | * ``UT_Never`` (in configuration: ``Never``) |
| 507 | Never use tab. |
| 508 | * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) |
| 509 | Use tabs only for indentation. |
| 510 | * ``UT_Always`` (in configuration: ``Always``) |
| 511 | Use tabs whenever we need to fill whitespace that spans at least from |
| 512 | one tab stop to the next one. |
| 513 | |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 514 | |
| 515 | .. END_FORMAT_STYLE_OPTIONS |
| 516 | |
| 517 | Examples |
| 518 | ======== |
| 519 | |
| 520 | A style similar to the `Linux Kernel style |
| 521 | <https://www.kernel.org/doc/Documentation/CodingStyle>`_: |
| 522 | |
| 523 | .. code-block:: yaml |
| 524 | |
| 525 | BasedOnStyle: LLVM |
| 526 | IndentWidth: 8 |
Alexander Kornienko | 62a5565 | 2013-09-27 16:19:25 +0000 | [diff] [blame] | 527 | UseTab: Always |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 528 | BreakBeforeBraces: Linux |
| 529 | AllowShortIfStatementsOnASingleLine: false |
| 530 | IndentCaseLabels: false |
| 531 | |
| 532 | The result is (imagine that tabs are used for indentation here): |
| 533 | |
| 534 | .. code-block:: c++ |
| 535 | |
| 536 | void test() |
| 537 | { |
| 538 | switch (x) { |
| 539 | case 0: |
| 540 | case 1: |
| 541 | do_something(); |
| 542 | break; |
| 543 | case 2: |
| 544 | do_something_else(); |
| 545 | break; |
| 546 | default: |
| 547 | break; |
| 548 | } |
| 549 | if (condition) |
| 550 | do_something_completely_different(); |
| 551 | |
| 552 | if (x == y) { |
| 553 | q(); |
| 554 | } else if (x > y) { |
| 555 | w(); |
| 556 | } else { |
| 557 | r(); |
| 558 | } |
| 559 | } |
| 560 | |
| 561 | A style similar to the default Visual Studio formatting style: |
| 562 | |
| 563 | .. code-block:: yaml |
| 564 | |
Alexander Kornienko | 62a5565 | 2013-09-27 16:19:25 +0000 | [diff] [blame] | 565 | UseTab: Never |
Alexander Kornienko | 62d06b7 | 2013-09-04 15:09:13 +0000 | [diff] [blame] | 566 | IndentWidth: 4 |
| 567 | BreakBeforeBraces: Allman |
| 568 | AllowShortIfStatementsOnASingleLine: false |
| 569 | IndentCaseLabels: false |
| 570 | ColumnLimit: 0 |
| 571 | |
| 572 | The result is: |
| 573 | |
| 574 | .. code-block:: c++ |
| 575 | |
| 576 | void test() |
| 577 | { |
| 578 | switch (suffix) |
| 579 | { |
| 580 | case 0: |
| 581 | case 1: |
| 582 | do_something(); |
| 583 | break; |
| 584 | case 2: |
| 585 | do_something_else(); |
| 586 | break; |
| 587 | default: |
| 588 | break; |
| 589 | } |
| 590 | if (condition) |
| 591 | do_somthing_completely_different(); |
| 592 | |
| 593 | if (x == y) |
| 594 | { |
| 595 | q(); |
| 596 | } |
| 597 | else if (x > y) |
| 598 | { |
| 599 | w(); |
| 600 | } |
| 601 | else |
| 602 | { |
| 603 | r(); |
| 604 | } |
| 605 | } |
| 606 | |