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**AlignAfterOpenBracket** (``BracketAlignmentStyle``) 154 If ``true``, horizontally aligns arguments after an open bracket. 155 156 This applies to round brackets (parentheses), angle brackets and square 157 brackets. 158 159 Possible values: 160 161 * ``BAS_Align`` (in configuration: ``Align``) 162 Align parameters on the open bracket, e.g.: 163 164 .. code-block:: c++ 165 166 someLongFunction(argument1, 167 argument2); 168 169 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 170 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 171 172 .. code-block:: c++ 173 174 someLongFunction(argument1, 175 argument2); 176 177 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 178 Always break after an open bracket, if the parameters don't fit 179 on a single line, e.g.: 180 181 .. code-block:: c++ 182 183 someLongFunction( 184 argument1, argument2); 185 186 187 188**AlignConsecutiveAssignments** (``bool``) 189 If ``true``, aligns consecutive assignments. 190 191 This will align the assignment operators of consecutive lines. This 192 will result in formattings like 193 194 .. code-block:: c++ 195 196 int aaaa = 12; 197 int b = 23; 198 int ccc = 23; 199 200**AlignConsecutiveDeclarations** (``bool``) 201 If ``true``, aligns consecutive declarations. 202 203 This will align the declaration names of consecutive lines. This 204 will result in formattings like 205 206 .. code-block:: c++ 207 208 int aaaa = 12; 209 float b = 23; 210 std::string ccc = 23; 211 212**AlignEscapedNewlinesLeft** (``bool``) 213 If ``true``, aligns escaped newlines as far left as possible. 214 Otherwise puts them into the right-most column. 215 216**AlignOperands** (``bool``) 217 If ``true``, horizontally align operands of binary and ternary 218 expressions. 219 220 Specifically, this aligns operands of a single expression that needs to be 221 split over multiple lines, e.g.: 222 223 .. code-block:: c++ 224 225 int aaa = bbbbbbbbbbbbbbb + 226 ccccccccccccccc; 227 228**AlignTrailingComments** (``bool``) 229 If ``true``, aligns trailing comments. 230 231**AllowAllParametersOfDeclarationOnNextLine** (``bool``) 232 Allow putting all parameters of a function declaration onto 233 the next line even if ``BinPackParameters`` is ``false``. 234 235**AllowShortBlocksOnASingleLine** (``bool``) 236 Allows contracting simple braced statements to a single line. 237 238 E.g., this allows ``if (a) { return; }`` to be put on a single line. 239 240**AllowShortCaseLabelsOnASingleLine** (``bool``) 241 If ``true``, short case labels will be contracted to a single line. 242 243**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) 244 Dependent on the value, ``int f() { return 0; }`` can be put on a 245 single line. 246 247 Possible values: 248 249 * ``SFS_None`` (in configuration: ``None``) 250 Never merge functions into a single line. 251 252 * ``SFS_Empty`` (in configuration: ``Empty``) 253 Only merge empty functions. 254 255 * ``SFS_Inline`` (in configuration: ``Inline``) 256 Only merge functions defined inside a class. Implies "empty". 257 258 * ``SFS_All`` (in configuration: ``All``) 259 Merge all functions fitting on a single line. 260 261 262 263**AllowShortIfStatementsOnASingleLine** (``bool``) 264 If ``true``, ``if (a) return;`` can be put on a single line. 265 266**AllowShortLoopsOnASingleLine** (``bool``) 267 If ``true``, ``while (true) continue;`` can be put on a single 268 line. 269 270**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) 271 The function definition return type breaking style to use. This 272 option is deprecated and is retained for backwards compatibility. 273 274 Possible values: 275 276 * ``DRTBS_None`` (in configuration: ``None``) 277 Break after return type automatically. 278 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 279 280 * ``DRTBS_All`` (in configuration: ``All``) 281 Always break after the return type. 282 283 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) 284 Always break after the return types of top-level functions. 285 286 287 288**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``) 289 The function declaration return type breaking style to use. 290 291 Possible values: 292 293 * ``RTBS_None`` (in configuration: ``None``) 294 Break after return type automatically. 295 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 296 297 * ``RTBS_All`` (in configuration: ``All``) 298 Always break after the return type. 299 300 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) 301 Always break after the return types of top-level functions. 302 303 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) 304 Always break after the return type of function definitions. 305 306 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) 307 Always break after the return type of top-level definitions. 308 309 310 311**AlwaysBreakBeforeMultilineStrings** (``bool``) 312 If ``true``, always break before multiline string literals. 313 314 This flag is mean to make cases where there are multiple multiline strings 315 in a file look more consistent. Thus, it will only take effect if wrapping 316 the string at that point leads to it being indented 317 ``ContinuationIndentWidth`` spaces from the start of the line. 318 319**AlwaysBreakTemplateDeclarations** (``bool``) 320 If ``true``, always break after the ``template<...>`` of a template 321 declaration. 322 323**BinPackArguments** (``bool``) 324 If ``false``, a function call's arguments will either be all on the 325 same line or will have one line each. 326 327**BinPackParameters** (``bool``) 328 If ``false``, a function declaration's or function definition's 329 parameters will either all be on the same line or will have one line each. 330 331**BraceWrapping** (``BraceWrappingFlags``) 332 Control of individual brace wrapping cases. 333 334 If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how 335 each individual brace case should be handled. Otherwise, this is ignored. 336 337 Nested configuration flags: 338 339 * ``bool AfterClass`` Wrap class definitions. 340 * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..). 341 * ``bool AfterEnum`` Wrap enum definitions. 342 * ``bool AfterFunction`` Wrap function definitions. 343 * ``bool AfterNamespace`` Wrap namespace definitions. 344 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..). 345 * ``bool AfterStruct`` Wrap struct definitions. 346 * ``bool AfterUnion`` Wrap union definitions. 347 * ``bool BeforeCatch`` Wrap before ``catch``. 348 * ``bool BeforeElse`` Wrap before ``else``. 349 * ``bool IndentBraces`` Indent the wrapped braces themselves. 350 351 352**BreakAfterJavaFieldAnnotations** (``bool``) 353 Break after each annotation on a field in Java files. 354 355**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) 356 The way to wrap binary operators. 357 358 Possible values: 359 360 * ``BOS_None`` (in configuration: ``None``) 361 Break after operators. 362 363 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) 364 Break before operators that aren't assignments. 365 366 * ``BOS_All`` (in configuration: ``All``) 367 Break before operators. 368 369 370 371**BreakBeforeBraces** (``BraceBreakingStyle``) 372 The brace breaking style to use. 373 374 Possible values: 375 376 * ``BS_Attach`` (in configuration: ``Attach``) 377 Always attach braces to surrounding context. 378 379 * ``BS_Linux`` (in configuration: ``Linux``) 380 Like ``Attach``, but break before braces on function, namespace and 381 class definitions. 382 383 * ``BS_Mozilla`` (in configuration: ``Mozilla``) 384 Like ``Attach``, but break before braces on enum, function, and record 385 definitions. 386 387 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) 388 Like ``Attach``, but break before function definitions, ``catch``, and 389 ``else``. 390 391 * ``BS_Allman`` (in configuration: ``Allman``) 392 Always break before braces. 393 394 * ``BS_GNU`` (in configuration: ``GNU``) 395 Always break before braces and add an extra level of indentation to 396 braces of control statements, not to those of class, function 397 or other definitions. 398 399 * ``BS_WebKit`` (in configuration: ``WebKit``) 400 Like ``Attach``, but break before functions. 401 402 * ``BS_Custom`` (in configuration: ``Custom``) 403 Configure each individual brace in `BraceWrapping`. 404 405 406 407**BreakBeforeTernaryOperators** (``bool``) 408 If ``true``, ternary operators will be placed after line breaks. 409 410**BreakConstructorInitializersBeforeComma** (``bool``) 411 Always break constructor initializers before commas and align 412 the commas with the colon. 413 414**BreakStringLiterals** (``bool``) 415 Allow breaking string literals when formatting. 416 417**ColumnLimit** (``unsigned``) 418 The column limit. 419 420 A column limit of ``0`` means that there is no column limit. In this case, 421 clang-format will respect the input's line breaking decisions within 422 statements unless they contradict other rules. 423 424**CommentPragmas** (``std::string``) 425 A regular expression that describes comments with special meaning, 426 which should not be split into lines or otherwise changed. 427 428**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) 429 If the constructor initializers don't fit on a line, put each 430 initializer on its own line. 431 432**ConstructorInitializerIndentWidth** (``unsigned``) 433 The number of characters to use for indentation of constructor 434 initializer lists. 435 436**ContinuationIndentWidth** (``unsigned``) 437 Indent width for line continuations. 438 439**Cpp11BracedListStyle** (``bool``) 440 If ``true``, format braced lists as best suited for C++11 braced 441 lists. 442 443 Important differences: 444 - No spaces inside the braced list. 445 - No line break before the closing brace. 446 - Indentation with the continuation indent, not with the block indent. 447 448 Fundamentally, C++11 braced lists are formatted exactly like function 449 calls would be formatted in their place. If the braced list follows a name 450 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 451 the parentheses of a function call with that name. If there is no name, 452 a zero-length name is assumed. 453 454**DerivePointerAlignment** (``bool``) 455 If ``true``, analyze the formatted file for the most common 456 alignment of ``&`` and ``\*``. ``PointerAlignment`` is then used only as 457 fallback. 458 459**DisableFormat** (``bool``) 460 Disables formatting completely. 461 462**ExperimentalAutoDetectBinPacking** (``bool``) 463 If ``true``, clang-format detects whether function calls and 464 definitions are formatted with one parameter per line. 465 466 Each call can be bin-packed, one-per-line or inconclusive. If it is 467 inconclusive, e.g. completely on one line, but a decision needs to be 468 made, clang-format analyzes whether there are other bin-packed cases in 469 the input file and act accordingly. 470 471 NOTE: This is an experimental flag, that might go away or be renamed. Do 472 not use this in config files, etc. Use at your own risk. 473 474**ForEachMacros** (``std::vector<std::string>``) 475 A vector of macros that should be interpreted as foreach loops 476 instead of as function calls. 477 478 These are expected to be macros of the form: 479 480 .. code-block:: c++ 481 482 FOREACH(<variable-declaration>, ...) 483 <loop-body> 484 485 In the .clang-format configuration file, this can be configured like: 486 487 .. code-block:: yaml 488 489 ForEachMacros: ['RANGES_FOR', 'FOREACH'] 490 491 For example: BOOST_FOREACH. 492 493**IncludeCategories** (``std::vector<IncludeCategory>``) 494 Regular expressions denoting the different ``#include`` categories 495 used for ordering ``#includes``. 496 497 These regular expressions are matched against the filename of an include 498 (including the <> or "") in order. The value belonging to the first 499 matching regular expression is assigned and ``#includes`` are sorted first 500 according to increasing category number and then alphabetically within 501 each category. 502 503 If none of the regular expressions match, INT_MAX is assigned as 504 category. The main header for a source file automatically gets category 0. 505 so that it is generally kept at the beginning of the ``#includes`` 506 (http://llvm.org/docs/CodingStandards.html#include-style). However, you 507 can also assign negative priorities if you have certain headers that 508 always need to be first. 509 510 To configure this in the .clang-format file, use: 511 512 .. code-block:: yaml 513 514 IncludeCategories: 515 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 516 Priority: 2 517 - Regex: '^(<|"(gtest|isl|json)/)' 518 Priority: 3 519 - Regex: '.\*' 520 Priority: 1 521 522**IncludeIsMainRegex** (``std::string``) 523 Specify a regular expression of suffixes that are allowed in the 524 file-to-main-include mapping. 525 526 When guessing whether a #include is the "main" include (to assign 527 category 0, see above), use this regex of allowed suffixes to the header 528 stem. A partial match is done, so that: 529 - "" means "arbitrary suffix" 530 - "$" means "no suffix" 531 532 For example, if configured to "(_test)?$", then a header a.h would be seen 533 as the "main" include in both a.cc and a_test.cc. 534 535**IndentCaseLabels** (``bool``) 536 Indent case labels one level from the switch statement. 537 538 When ``false``, use the same indentation level as for the switch statement. 539 Switch statement body is always indented one level more than case labels. 540 541**IndentWidth** (``unsigned``) 542 The number of columns to use for indentation. 543 544**IndentWrappedFunctionNames** (``bool``) 545 Indent if a function definition or declaration is wrapped after the 546 type. 547 548**JavaScriptQuotes** (``JavaScriptQuoteStyle``) 549 The JavaScriptQuoteStyle to use for JavaScript strings. 550 551 Possible values: 552 553 * ``JSQS_Leave`` (in configuration: ``Leave``) 554 Leave string quotes as they are. 555 556 * ``JSQS_Single`` (in configuration: ``Single``) 557 Always use single quotes. 558 559 * ``JSQS_Double`` (in configuration: ``Double``) 560 Always use double quotes. 561 562 563 564**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) 565 If true, empty lines at the start of blocks are kept. 566 567**Language** (``LanguageKind``) 568 Language, this format style is targeted at. 569 570 Possible values: 571 572 * ``LK_None`` (in configuration: ``None``) 573 Do not use. 574 575 * ``LK_Cpp`` (in configuration: ``Cpp``) 576 Should be used for C, C++, ObjectiveC, ObjectiveC++. 577 578 * ``LK_Java`` (in configuration: ``Java``) 579 Should be used for Java. 580 581 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 582 Should be used for JavaScript. 583 584 * ``LK_Proto`` (in configuration: ``Proto``) 585 Should be used for Protocol Buffers 586 (https://developers.google.com/protocol-buffers/). 587 588 * ``LK_TableGen`` (in configuration: ``TableGen``) 589 Should be used for TableGen code. 590 591 592 593**MacroBlockBegin** (``std::string``) 594 A regular expression matching macros that start a block. 595 596**MacroBlockEnd** (``std::string``) 597 A regular expression matching macros that end a block. 598 599**MaxEmptyLinesToKeep** (``unsigned``) 600 The maximum number of consecutive empty lines to keep. 601 602**NamespaceIndentation** (``NamespaceIndentationKind``) 603 The indentation used for namespaces. 604 605 Possible values: 606 607 * ``NI_None`` (in configuration: ``None``) 608 Don't indent in namespaces. 609 610 * ``NI_Inner`` (in configuration: ``Inner``) 611 Indent only in inner namespaces (nested in other namespaces). 612 613 * ``NI_All`` (in configuration: ``All``) 614 Indent in all namespaces. 615 616 617 618**ObjCBlockIndentWidth** (``unsigned``) 619 The number of characters to use for indentation of ObjC blocks. 620 621**ObjCSpaceAfterProperty** (``bool``) 622 Add a space after ``@property`` in Objective-C, i.e. use 623 ``@property (readonly)`` instead of ``@property(readonly)``. 624 625**ObjCSpaceBeforeProtocolList** (``bool``) 626 Add a space in front of an Objective-C protocol list, i.e. use 627 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 628 629**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) 630 The penalty for breaking a function call after ``call(``. 631 632**PenaltyBreakComment** (``unsigned``) 633 The penalty for each line break introduced inside a comment. 634 635**PenaltyBreakFirstLessLess** (``unsigned``) 636 The penalty for breaking before the first ``<<``. 637 638**PenaltyBreakString** (``unsigned``) 639 The penalty for each line break introduced inside a string literal. 640 641**PenaltyExcessCharacter** (``unsigned``) 642 The penalty for each character outside of the column limit. 643 644**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) 645 Penalty for putting the return type of a function onto its own 646 line. 647 648**PointerAlignment** (``PointerAlignmentStyle``) 649 Pointer and reference alignment style. 650 651 Possible values: 652 653 * ``PAS_Left`` (in configuration: ``Left``) 654 Align pointer to the left. 655 656 * ``PAS_Right`` (in configuration: ``Right``) 657 Align pointer to the right. 658 659 * ``PAS_Middle`` (in configuration: ``Middle``) 660 Align pointer in the middle. 661 662 663 664**ReflowComments** (``bool``) 665 If ``true``, clang-format will attempt to re-flow comments. 666 667**SortIncludes** (``bool``) 668 If ``true``, clang-format will sort ``#includes``. 669 670**SpaceAfterCStyleCast** (``bool``) 671 If ``true``, a space may be inserted after C style casts. 672 673**SpaceBeforeAssignmentOperators** (``bool``) 674 If ``false``, spaces will be removed before assignment operators. 675 676**SpaceBeforeParens** (``SpaceBeforeParensOptions``) 677 Defines in which cases to put a space before opening parentheses. 678 679 Possible values: 680 681 * ``SBPO_Never`` (in configuration: ``Never``) 682 Never put a space before opening parentheses. 683 684 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 685 Put a space before opening parentheses only after control statement 686 keywords (``for/if/while...``). 687 688 * ``SBPO_Always`` (in configuration: ``Always``) 689 Always put a space before opening parentheses, except when it's 690 prohibited by the syntax rules (in function-like macro definitions) or 691 when determined by other style rules (after unary operators, opening 692 parentheses, etc.) 693 694 695 696**SpaceInEmptyParentheses** (``bool``) 697 If ``true``, spaces may be inserted into ``()``. 698 699**SpacesBeforeTrailingComments** (``unsigned``) 700 The number of spaces before trailing line comments 701 (``//`` - comments). 702 703 This does not affect trailing block comments (``/*`` - comments) as 704 those commonly have different usage patterns and a number of special 705 cases. 706 707**SpacesInAngles** (``bool``) 708 If ``true``, spaces will be inserted after ``<`` and before ``>`` 709 in template argument lists. 710 711**SpacesInCStyleCastParentheses** (``bool``) 712 If ``true``, spaces may be inserted into C style casts. 713 714**SpacesInContainerLiterals** (``bool``) 715 If ``true``, spaces are inserted inside container literals (e.g. 716 ObjC and Javascript array and dict literals). 717 718**SpacesInParentheses** (``bool``) 719 If ``true``, spaces will be inserted after ``(`` and before ``)``. 720 721**SpacesInSquareBrackets** (``bool``) 722 If ``true``, spaces will be inserted after ``[`` and before ``]``. 723 724**Standard** (``LanguageStandard``) 725 Format compatible with this standard, e.g. use ``A<A<int> >`` 726 instead of ``A<A<int>>`` for ``LS_Cpp03``. 727 728 Possible values: 729 730 * ``LS_Cpp03`` (in configuration: ``Cpp03``) 731 Use C++03-compatible syntax. 732 733 * ``LS_Cpp11`` (in configuration: ``Cpp11``) 734 Use features of C++11 (e.g. ``A<A<int>>`` instead of ``A<A<int> >``). 735 736 * ``LS_Auto`` (in configuration: ``Auto``) 737 Automatic detection based on the input. 738 739 740 741**TabWidth** (``unsigned``) 742 The number of columns used for tab stops. 743 744**UseTab** (``UseTabStyle``) 745 The way to use tab characters in the resulting file. 746 747 Possible values: 748 749 * ``UT_Never`` (in configuration: ``Never``) 750 Never use tab. 751 752 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 753 Use tabs only for indentation. 754 755 * ``UT_Always`` (in configuration: ``Always``) 756 Use tabs whenever we need to fill whitespace that spans at least from 757 one tab stop to the next one. 758 759 760 761.. END_FORMAT_STYLE_OPTIONS 762 763Adding additional style options 764=============================== 765 766Each additional style option adds costs to the clang-format project. Some of 767these costs affect the clang-format development itself, as we need to make 768sure that any given combination of options work and that new features don't 769break any of the existing options in any way. There are also costs for end users 770as options become less discoverable and people have to think about and make a 771decision on options they don't really care about. 772 773The goal of the clang-format project is more on the side of supporting a 774limited set of styles really well as opposed to supporting every single style 775used by a codebase somewhere in the wild. Of course, we do want to support all 776major projects and thus have established the following bar for adding style 777options. Each new style option must .. 778 779 * be used in a project of significant size (have dozens of contributors) 780 * have a publicly accessible style guide 781 * have a person willing to contribute and maintain patches 782 783Examples 784======== 785 786A style similar to the `Linux Kernel style 787<https://www.kernel.org/doc/Documentation/CodingStyle>`_: 788 789.. code-block:: yaml 790 791 BasedOnStyle: LLVM 792 IndentWidth: 8 793 UseTab: Always 794 BreakBeforeBraces: Linux 795 AllowShortIfStatementsOnASingleLine: false 796 IndentCaseLabels: false 797 798The result is (imagine that tabs are used for indentation here): 799 800.. code-block:: c++ 801 802 void test() 803 { 804 switch (x) { 805 case 0: 806 case 1: 807 do_something(); 808 break; 809 case 2: 810 do_something_else(); 811 break; 812 default: 813 break; 814 } 815 if (condition) 816 do_something_completely_different(); 817 818 if (x == y) { 819 q(); 820 } else if (x > y) { 821 w(); 822 } else { 823 r(); 824 } 825 } 826 827A style similar to the default Visual Studio formatting style: 828 829.. code-block:: yaml 830 831 UseTab: Never 832 IndentWidth: 4 833 BreakBeforeBraces: Allman 834 AllowShortIfStatementsOnASingleLine: false 835 IndentCaseLabels: false 836 ColumnLimit: 0 837 838The result is: 839 840.. code-block:: c++ 841 842 void test() 843 { 844 switch (suffix) 845 { 846 case 0: 847 case 1: 848 do_something(); 849 break; 850 case 2: 851 do_something_else(); 852 break; 853 default: 854 break; 855 } 856 if (condition) 857 do_somthing_completely_different(); 858 859 if (x == y) 860 { 861 q(); 862 } 863 else if (x > y) 864 { 865 w(); 866 } 867 else 868 { 869 r(); 870 } 871 } 872 873