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