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