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, Microsoft) or 11create a custom 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 Language: CSharp 73 # Use 100 columns for C#. 74 ColumnLimit: 100 75 ... 76 77An easy way to get a valid ``.clang-format`` file containing all configuration 78options of a certain predefined style is: 79 80.. code-block:: console 81 82 clang-format -style=llvm -dump-config > .clang-format 83 84When specifying configuration in the ``-style=`` option, the same configuration 85is applied for all input files. The format of the configuration is: 86 87.. code-block:: console 88 89 -style='{key1: value1, key2: value2, ...}' 90 91 92Disabling Formatting on a Piece of Code 93======================================= 94 95Clang-format understands also special comments that switch formatting in a 96delimited range. The code between a comment ``// clang-format off`` or 97``/* clang-format off */`` up to a comment ``// clang-format on`` or 98``/* clang-format on */`` will not be formatted. The comments themselves 99will be formatted (aligned) normally. 100 101.. code-block:: c++ 102 103 int formatted_code; 104 // clang-format off 105 void unformatted_code ; 106 // clang-format on 107 void formatted_code_again; 108 109 110Configuring Style in Code 111========================= 112 113When using ``clang::format::reformat(...)`` functions, the format is specified 114by supplying the `clang::format::FormatStyle 115<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_ 116structure. 117 118 119Configurable Format Style Options 120================================= 121 122This section lists the supported style options. Value type is specified for 123each option. For enumeration types possible values are specified both as a C++ 124enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in 125the configuration (without a prefix: ``Auto``). 126 127 128**BasedOnStyle** (``string``) 129 The style used for all options not specifically set in the configuration. 130 131 This option is supported only in the :program:`clang-format` configuration 132 (both within ``-style='{...}'`` and the ``.clang-format`` file). 133 134 Possible values: 135 136 * ``LLVM`` 137 A style complying with the `LLVM coding standards 138 <https://llvm.org/docs/CodingStandards.html>`_ 139 * ``Google`` 140 A style complying with `Google's C++ style guide 141 <https://google.github.io/styleguide/cppguide.html>`_ 142 * ``Chromium`` 143 A style complying with `Chromium's style guide 144 <https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md>`_ 145 * ``Mozilla`` 146 A style complying with `Mozilla's style guide 147 <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_ 148 * ``WebKit`` 149 A style complying with `WebKit's style guide 150 <https://www.webkit.org/coding/coding-style.html>`_ 151 * ``Microsoft`` 152 A style complying with `Microsoft's style guide 153 <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_ 154 * ``GNU`` 155 A style complying with the `GNU coding standards 156 <https://www.gnu.org/prep/standards/standards.html>`_ 157 158.. START_FORMAT_STYLE_OPTIONS 159 160**AccessModifierOffset** (``int``) 161 The extra indent or outdent of access modifiers, e.g. ``public:``. 162 163**AlignAfterOpenBracket** (``BracketAlignmentStyle``) 164 If ``true``, horizontally aligns arguments after an open bracket. 165 166 This applies to round brackets (parentheses), angle brackets and square 167 brackets. 168 169 Possible values: 170 171 * ``BAS_Align`` (in configuration: ``Align``) 172 Align parameters on the open bracket, e.g.: 173 174 .. code-block:: c++ 175 176 someLongFunction(argument1, 177 argument2); 178 179 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 180 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 181 182 .. code-block:: c++ 183 184 someLongFunction(argument1, 185 argument2); 186 187 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 188 Always break after an open bracket, if the parameters don't fit 189 on a single line, e.g.: 190 191 .. code-block:: c++ 192 193 someLongFunction( 194 argument1, argument2); 195 196 197 198**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) 199 Style of aligning consecutive assignments. 200 201 ``Consecutive`` will result in formattings like: 202 203 .. code-block:: c++ 204 205 int a = 1; 206 int somelongname = 2; 207 double c = 3; 208 209 Possible values: 210 211 * ``ACS_None`` (in configuration: ``None``) 212 Do not align assignments on consecutive lines. 213 214 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 215 Align assignments on consecutive lines. This will result in 216 formattings like: 217 218 .. code-block:: c++ 219 220 int a = 1; 221 int somelongname = 2; 222 double c = 3; 223 224 int d = 3; 225 /* A comment. */ 226 double e = 4; 227 228 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 229 Same as ACS_Consecutive, but also spans over empty lines, e.g. 230 231 .. code-block:: c++ 232 233 int a = 1; 234 int somelongname = 2; 235 double c = 3; 236 237 int d = 3; 238 /* A comment. */ 239 double e = 4; 240 241 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 242 Same as ACS_Consecutive, but also spans over lines only containing 243 comments, e.g. 244 245 .. code-block:: c++ 246 247 int a = 1; 248 int somelongname = 2; 249 double c = 3; 250 251 int d = 3; 252 /* A comment. */ 253 double e = 4; 254 255 * ``ACS_AcrossEmptyLinesAndComments`` 256 (in configuration: ``AcrossEmptyLinesAndComments``) 257 258 Same as ACS_Consecutive, but also spans over lines only containing 259 comments and empty lines, e.g. 260 261 .. code-block:: c++ 262 263 int a = 1; 264 int somelongname = 2; 265 double c = 3; 266 267 int d = 3; 268 /* A comment. */ 269 double e = 4; 270 271**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) 272 Style of aligning consecutive bit field. 273 274 ``Consecutive`` will align the bitfield separators of consecutive lines. 275 This will result in formattings like: 276 277 .. code-block:: c++ 278 279 int aaaa : 1; 280 int b : 12; 281 int ccc : 8; 282 283 Possible values: 284 285 * ``ACS_None`` (in configuration: ``None``) 286 Do not align bit fields on consecutive lines. 287 288 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 289 Align bit fields on consecutive lines. This will result in 290 formattings like: 291 292 .. code-block:: c++ 293 294 int aaaa : 1; 295 int b : 12; 296 int ccc : 8; 297 298 int d : 2; 299 /* A comment. */ 300 int ee : 3; 301 302 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 303 Same as ACS_Consecutive, but also spans over empty lines, e.g. 304 305 .. code-block:: c++ 306 307 int aaaa : 1; 308 int b : 12; 309 int ccc : 8; 310 311 int d : 2; 312 /* A comment. */ 313 int ee : 3; 314 315 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 316 Same as ACS_Consecutive, but also spans over lines only containing 317 comments, e.g. 318 319 .. code-block:: c++ 320 321 int aaaa : 1; 322 int b : 12; 323 int ccc : 8; 324 325 int d : 2; 326 /* A comment. */ 327 int ee : 3; 328 329 * ``ACS_AcrossEmptyLinesAndComments`` 330 (in configuration: ``AcrossEmptyLinesAndComments``) 331 332 Same as ACS_Consecutive, but also spans over lines only containing 333 comments and empty lines, e.g. 334 335 .. code-block:: c++ 336 337 int aaaa : 1; 338 int b : 12; 339 int ccc : 8; 340 341 int d : 2; 342 /* A comment. */ 343 int ee : 3; 344 345**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) 346 Style of aligning consecutive declarations. 347 348 ``Consecutive`` will align the declaration names of consecutive lines. 349 This will result in formattings like: 350 351 .. code-block:: c++ 352 353 int aaaa = 12; 354 float b = 23; 355 std::string ccc; 356 357 Possible values: 358 359 * ``ACS_None`` (in configuration: ``None``) 360 Do not align bit declarations on consecutive lines. 361 362 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 363 Align declarations on consecutive lines. This will result in 364 formattings like: 365 366 .. code-block:: c++ 367 368 int aaaa = 12; 369 float b = 23; 370 std::string ccc; 371 372 int a = 42; 373 /* A comment. */ 374 bool c = false; 375 376 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 377 Same as ACS_Consecutive, but also spans over empty lines, e.g. 378 379 .. code-block:: c++ 380 381 int aaaa = 12; 382 float b = 23; 383 std::string ccc; 384 385 int a = 42; 386 /* A comment. */ 387 bool c = false; 388 389 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 390 Same as ACS_Consecutive, but also spans over lines only containing 391 comments, e.g. 392 393 .. code-block:: c++ 394 395 int aaaa = 12; 396 float b = 23; 397 std::string ccc; 398 399 int a = 42; 400 /* A comment. */ 401 bool c = false; 402 403 * ``ACS_AcrossEmptyLinesAndComments`` 404 (in configuration: ``AcrossEmptyLinesAndComments``) 405 406 Same as ACS_Consecutive, but also spans over lines only containing 407 comments and empty lines, e.g. 408 409 .. code-block:: c++ 410 411 int aaaa = 12; 412 float b = 23; 413 std::string ccc; 414 415 int a = 42; 416 /* A comment. */ 417 bool c = false; 418 419**AlignConsecutiveMacros** (``AlignConsecutiveStyle``) 420 Style of aligning consecutive macro definitions. 421 422 ``Consecutive`` will result in formattings like: 423 424 .. code-block:: c++ 425 426 #define SHORT_NAME 42 427 #define LONGER_NAME 0x007f 428 #define EVEN_LONGER_NAME (2) 429 #define foo(x) (x * x) 430 #define bar(y, z) (y + z) 431 432 Possible values: 433 434 * ``ACS_None`` (in configuration: ``None``) 435 Do not align macro definitions on consecutive lines. 436 437 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 438 Align macro definitions on consecutive lines. This will result in 439 formattings like: 440 441 .. code-block:: c++ 442 443 #define SHORT_NAME 42 444 #define LONGER_NAME 0x007f 445 #define EVEN_LONGER_NAME (2) 446 447 #define foo(x) (x * x) 448 /* some comment */ 449 #define bar(y, z) (y + z) 450 451 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 452 Same as ACS_Consecutive, but also spans over empty lines, e.g. 453 454 .. code-block:: c++ 455 456 #define SHORT_NAME 42 457 #define LONGER_NAME 0x007f 458 #define EVEN_LONGER_NAME (2) 459 460 #define foo(x) (x * x) 461 /* some comment */ 462 #define bar(y, z) (y + z) 463 464 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 465 Same as ACS_Consecutive, but also spans over lines only containing 466 comments, e.g. 467 468 .. code-block:: c++ 469 470 #define SHORT_NAME 42 471 #define LONGER_NAME 0x007f 472 #define EVEN_LONGER_NAME (2) 473 474 #define foo(x) (x * x) 475 /* some comment */ 476 #define bar(y, z) (y + z) 477 478 * ``ACS_AcrossEmptyLinesAndComments`` 479 (in configuration: ``AcrossEmptyLinesAndComments``) 480 481 Same as ACS_Consecutive, but also spans over lines only containing 482 comments and empty lines, e.g. 483 484 .. code-block:: c++ 485 486 #define SHORT_NAME 42 487 #define LONGER_NAME 0x007f 488 #define EVEN_LONGER_NAME (2) 489 490 #define foo(x) (x * x) 491 /* some comment */ 492 #define bar(y, z) (y + z) 493 494**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) 495 Options for aligning backslashes in escaped newlines. 496 497 Possible values: 498 499 * ``ENAS_DontAlign`` (in configuration: ``DontAlign``) 500 Don't align escaped newlines. 501 502 .. code-block:: c++ 503 504 #define A \ 505 int aaaa; \ 506 int b; \ 507 int dddddddddd; 508 509 * ``ENAS_Left`` (in configuration: ``Left``) 510 Align escaped newlines as far left as possible. 511 512 .. code-block:: c++ 513 514 true: 515 #define A \ 516 int aaaa; \ 517 int b; \ 518 int dddddddddd; 519 520 false: 521 522 * ``ENAS_Right`` (in configuration: ``Right``) 523 Align escaped newlines in the right-most column. 524 525 .. code-block:: c++ 526 527 #define A \ 528 int aaaa; \ 529 int b; \ 530 int dddddddddd; 531 532 533 534**AlignOperands** (``OperandAlignmentStyle``) 535 If ``true``, horizontally align operands of binary and ternary 536 expressions. 537 538 Possible values: 539 540 * ``OAS_DontAlign`` (in configuration: ``DontAlign``) 541 Do not align operands of binary and ternary expressions. 542 The wrapped lines are indented ``ContinuationIndentWidth`` spaces from 543 the start of the line. 544 545 * ``OAS_Align`` (in configuration: ``Align``) 546 Horizontally align operands of binary and ternary expressions. 547 548 Specifically, this aligns operands of a single expression that needs 549 to be split over multiple lines, e.g.: 550 551 .. code-block:: c++ 552 553 int aaa = bbbbbbbbbbbbbbb + 554 ccccccccccccccc; 555 556 When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is 557 aligned with the operand on the first line. 558 559 .. code-block:: c++ 560 561 int aaa = bbbbbbbbbbbbbbb 562 + ccccccccccccccc; 563 564 * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``) 565 Horizontally align operands of binary and ternary expressions. 566 567 This is similar to ``AO_Align``, except when 568 ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so 569 that the wrapped operand is aligned with the operand on the first line. 570 571 .. code-block:: c++ 572 573 int aaa = bbbbbbbbbbbbbbb 574 + ccccccccccccccc; 575 576 577 578**AlignTrailingComments** (``bool``) 579 If ``true``, aligns trailing comments. 580 581 .. code-block:: c++ 582 583 true: false: 584 int a; // My comment a vs. int a; // My comment a 585 int b = 2; // comment b int b = 2; // comment about b 586 587**AllowAllArgumentsOnNextLine** (``bool``) 588 If a function call or braced initializer list doesn't fit on a 589 line, allow putting all arguments onto the next line, even if 590 ``BinPackArguments`` is ``false``. 591 592 .. code-block:: c++ 593 594 true: 595 callFunction( 596 a, b, c, d); 597 598 false: 599 callFunction(a, 600 b, 601 c, 602 d); 603 604**AllowAllConstructorInitializersOnNextLine** (``bool``) 605 If a constructor definition with a member initializer list doesn't 606 fit on a single line, allow putting all member initializers onto the next 607 line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true. 608 Note that this parameter has no effect if 609 ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false. 610 611 .. code-block:: c++ 612 613 true: 614 MyClass::MyClass() : 615 member0(0), member1(2) {} 616 617 false: 618 MyClass::MyClass() : 619 member0(0), 620 member1(2) {} 621 622**AllowAllParametersOfDeclarationOnNextLine** (``bool``) 623 If the function declaration doesn't fit on a line, 624 allow putting all parameters of a function declaration onto 625 the next line even if ``BinPackParameters`` is ``false``. 626 627 .. code-block:: c++ 628 629 true: 630 void myFunction( 631 int a, int b, int c, int d, int e); 632 633 false: 634 void myFunction(int a, 635 int b, 636 int c, 637 int d, 638 int e); 639 640**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) 641 Dependent on the value, ``while (true) { continue; }`` can be put on a 642 single line. 643 644 Possible values: 645 646 * ``SBS_Never`` (in configuration: ``Never``) 647 Never merge blocks into a single line. 648 649 .. code-block:: c++ 650 651 while (true) { 652 } 653 while (true) { 654 continue; 655 } 656 657 * ``SBS_Empty`` (in configuration: ``Empty``) 658 Only merge empty blocks. 659 660 .. code-block:: c++ 661 662 while (true) {} 663 while (true) { 664 continue; 665 } 666 667 * ``SBS_Always`` (in configuration: ``Always``) 668 Always merge short blocks into a single line. 669 670 .. code-block:: c++ 671 672 while (true) {} 673 while (true) { continue; } 674 675 676 677**AllowShortCaseLabelsOnASingleLine** (``bool``) 678 If ``true``, short case labels will be contracted to a single line. 679 680 .. code-block:: c++ 681 682 true: false: 683 switch (a) { vs. switch (a) { 684 case 1: x = 1; break; case 1: 685 case 2: return; x = 1; 686 } break; 687 case 2: 688 return; 689 } 690 691**AllowShortEnumsOnASingleLine** (``bool``) 692 Allow short enums on a single line. 693 694 .. code-block:: c++ 695 696 true: 697 enum { A, B } myEnum; 698 699 false: 700 enum 701 { 702 A, 703 B 704 } myEnum; 705 706**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) 707 Dependent on the value, ``int f() { return 0; }`` can be put on a 708 single line. 709 710 Possible values: 711 712 * ``SFS_None`` (in configuration: ``None``) 713 Never merge functions into a single line. 714 715 * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) 716 Only merge functions defined inside a class. Same as "inline", 717 except it does not implies "empty": i.e. top level empty functions 718 are not merged either. 719 720 .. code-block:: c++ 721 722 class Foo { 723 void f() { foo(); } 724 }; 725 void f() { 726 foo(); 727 } 728 void f() { 729 } 730 731 * ``SFS_Empty`` (in configuration: ``Empty``) 732 Only merge empty functions. 733 734 .. code-block:: c++ 735 736 void f() {} 737 void f2() { 738 bar2(); 739 } 740 741 * ``SFS_Inline`` (in configuration: ``Inline``) 742 Only merge functions defined inside a class. Implies "empty". 743 744 .. code-block:: c++ 745 746 class Foo { 747 void f() { foo(); } 748 }; 749 void f() { 750 foo(); 751 } 752 void f() {} 753 754 * ``SFS_All`` (in configuration: ``All``) 755 Merge all functions fitting on a single line. 756 757 .. code-block:: c++ 758 759 class Foo { 760 void f() { foo(); } 761 }; 762 void f() { bar(); } 763 764 765 766**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) 767 If ``true``, ``if (a) return;`` can be put on a single line. 768 769 Possible values: 770 771 * ``SIS_Never`` (in configuration: ``Never``) 772 Never put short ifs on the same line. 773 774 .. code-block:: c++ 775 776 if (a) 777 return ; 778 else { 779 return; 780 } 781 782 * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``) 783 Without else put short ifs on the same line only if 784 the else is not a compound statement. 785 786 .. code-block:: c++ 787 788 if (a) return; 789 else 790 return; 791 792 * ``SIS_Always`` (in configuration: ``Always``) 793 Always put short ifs on the same line if 794 the else is not a compound statement or not. 795 796 .. code-block:: c++ 797 798 if (a) return; 799 else { 800 return; 801 } 802 803 804 805**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) 806 Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a 807 single line. 808 809 Possible values: 810 811 * ``SLS_None`` (in configuration: ``None``) 812 Never merge lambdas into a single line. 813 814 * ``SLS_Empty`` (in configuration: ``Empty``) 815 Only merge empty lambdas. 816 817 .. code-block:: c++ 818 819 auto lambda = [](int a) {} 820 auto lambda2 = [](int a) { 821 return a; 822 }; 823 824 * ``SLS_Inline`` (in configuration: ``Inline``) 825 Merge lambda into a single line if argument of a function. 826 827 .. code-block:: c++ 828 829 auto lambda = [](int a) { 830 return a; 831 }; 832 sort(a.begin(), a.end(), ()[] { return x < y; }) 833 834 * ``SLS_All`` (in configuration: ``All``) 835 Merge all lambdas fitting on a single line. 836 837 .. code-block:: c++ 838 839 auto lambda = [](int a) {} 840 auto lambda2 = [](int a) { return a; }; 841 842 843 844**AllowShortLoopsOnASingleLine** (``bool``) 845 If ``true``, ``while (true) continue;`` can be put on a single 846 line. 847 848**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) 849 The function definition return type breaking style to use. This 850 option is **deprecated** and is retained for backwards compatibility. 851 852 Possible values: 853 854 * ``DRTBS_None`` (in configuration: ``None``) 855 Break after return type automatically. 856 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 857 858 * ``DRTBS_All`` (in configuration: ``All``) 859 Always break after the return type. 860 861 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) 862 Always break after the return types of top-level functions. 863 864 865 866**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``) 867 The function declaration return type breaking style to use. 868 869 Possible values: 870 871 * ``RTBS_None`` (in configuration: ``None``) 872 Break after return type automatically. 873 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 874 875 .. code-block:: c++ 876 877 class A { 878 int f() { return 0; }; 879 }; 880 int f(); 881 int f() { return 1; } 882 883 * ``RTBS_All`` (in configuration: ``All``) 884 Always break after the return type. 885 886 .. code-block:: c++ 887 888 class A { 889 int 890 f() { 891 return 0; 892 }; 893 }; 894 int 895 f(); 896 int 897 f() { 898 return 1; 899 } 900 901 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) 902 Always break after the return types of top-level functions. 903 904 .. code-block:: c++ 905 906 class A { 907 int f() { return 0; }; 908 }; 909 int 910 f(); 911 int 912 f() { 913 return 1; 914 } 915 916 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) 917 Always break after the return type of function definitions. 918 919 .. code-block:: c++ 920 921 class A { 922 int 923 f() { 924 return 0; 925 }; 926 }; 927 int f(); 928 int 929 f() { 930 return 1; 931 } 932 933 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) 934 Always break after the return type of top-level definitions. 935 936 .. code-block:: c++ 937 938 class A { 939 int f() { return 0; }; 940 }; 941 int f(); 942 int 943 f() { 944 return 1; 945 } 946 947 948 949**AlwaysBreakBeforeMultilineStrings** (``bool``) 950 If ``true``, always break before multiline string literals. 951 952 This flag is mean to make cases where there are multiple multiline strings 953 in a file look more consistent. Thus, it will only take effect if wrapping 954 the string at that point leads to it being indented 955 ``ContinuationIndentWidth`` spaces from the start of the line. 956 957 .. code-block:: c++ 958 959 true: false: 960 aaaa = vs. aaaa = "bbbb" 961 "bbbb" "cccc"; 962 "cccc"; 963 964**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) 965 The template declaration breaking style to use. 966 967 Possible values: 968 969 * ``BTDS_No`` (in configuration: ``No``) 970 Do not force break before declaration. 971 ``PenaltyBreakTemplateDeclaration`` is taken into account. 972 973 .. code-block:: c++ 974 975 template <typename T> T foo() { 976 } 977 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, 978 int bbbbbbbbbbbbbbbbbbbbb) { 979 } 980 981 * ``BTDS_MultiLine`` (in configuration: ``MultiLine``) 982 Force break after template declaration only when the following 983 declaration spans multiple lines. 984 985 .. code-block:: c++ 986 987 template <typename T> T foo() { 988 } 989 template <typename T> 990 T foo(int aaaaaaaaaaaaaaaaaaaaa, 991 int bbbbbbbbbbbbbbbbbbbbb) { 992 } 993 994 * ``BTDS_Yes`` (in configuration: ``Yes``) 995 Always break after template declaration. 996 997 .. code-block:: c++ 998 999 template <typename T> 1000 T foo() { 1001 } 1002 template <typename T> 1003 T foo(int aaaaaaaaaaaaaaaaaaaaa, 1004 int bbbbbbbbbbbbbbbbbbbbb) { 1005 } 1006 1007 1008 1009**AttributeMacros** (``std::vector<std::string>``) 1010 A vector of strings that should be interpreted as attributes/qualifiers 1011 instead of identifiers. This can be useful for language extensions or 1012 static analyzer annotations. 1013 1014 For example: 1015 1016 .. code-block:: c++ 1017 1018 x = (char *__capability)&y; 1019 int function(void) __ununsed; 1020 void only_writes_to_buffer(char *__output buffer); 1021 1022 In the .clang-format configuration file, this can be configured like: 1023 1024 .. code-block:: yaml 1025 1026 AttributeMacros: ['__capability', '__output', '__ununsed'] 1027 1028**BinPackArguments** (``bool``) 1029 If ``false``, a function call's arguments will either be all on the 1030 same line or will have one line each. 1031 1032 .. code-block:: c++ 1033 1034 true: 1035 void f() { 1036 f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, 1037 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 1038 } 1039 1040 false: 1041 void f() { 1042 f(aaaaaaaaaaaaaaaaaaaa, 1043 aaaaaaaaaaaaaaaaaaaa, 1044 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 1045 } 1046 1047**BinPackParameters** (``bool``) 1048 If ``false``, a function declaration's or function definition's 1049 parameters will either all be on the same line or will have one line each. 1050 1051 .. code-block:: c++ 1052 1053 true: 1054 void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa, 1055 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 1056 1057 false: 1058 void f(int aaaaaaaaaaaaaaaaaaaa, 1059 int aaaaaaaaaaaaaaaaaaaa, 1060 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 1061 1062**BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) 1063 The BitFieldColonSpacingStyle to use for bitfields. 1064 1065 Possible values: 1066 1067 * ``BFCS_Both`` (in configuration: ``Both``) 1068 Add one space on each side of the ``:`` 1069 1070 .. code-block:: c++ 1071 1072 unsigned bf : 2; 1073 1074 * ``BFCS_None`` (in configuration: ``None``) 1075 Add no space around the ``:`` (except when needed for 1076 ``AlignConsecutiveBitFields``). 1077 1078 .. code-block:: c++ 1079 1080 unsigned bf:2; 1081 1082 * ``BFCS_Before`` (in configuration: ``Before``) 1083 Add space before the ``:`` only 1084 1085 .. code-block:: c++ 1086 1087 unsigned bf :2; 1088 1089 * ``BFCS_After`` (in configuration: ``After``) 1090 Add space after the ``:`` only (space may be added before if 1091 needed for ``AlignConsecutiveBitFields``). 1092 1093 .. code-block:: c++ 1094 1095 unsigned bf: 2; 1096 1097 1098 1099**BraceWrapping** (``BraceWrappingFlags``) 1100 Control of individual brace wrapping cases. 1101 1102 If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how 1103 each individual brace case should be handled. Otherwise, this is ignored. 1104 1105 .. code-block:: yaml 1106 1107 # Example of usage: 1108 BreakBeforeBraces: Custom 1109 BraceWrapping: 1110 AfterEnum: true 1111 AfterStruct: false 1112 SplitEmptyFunction: false 1113 1114 Nested configuration flags: 1115 1116 1117 * ``bool AfterCaseLabel`` Wrap case labels. 1118 1119 .. code-block:: c++ 1120 1121 false: true: 1122 switch (foo) { vs. switch (foo) { 1123 case 1: { case 1: 1124 bar(); { 1125 break; bar(); 1126 } break; 1127 default: { } 1128 plop(); default: 1129 } { 1130 } plop(); 1131 } 1132 } 1133 1134 * ``bool AfterClass`` Wrap class definitions. 1135 1136 .. code-block:: c++ 1137 1138 true: 1139 class foo {}; 1140 1141 false: 1142 class foo 1143 {}; 1144 1145 * ``BraceWrappingAfterControlStatementStyle AfterControlStatement`` 1146 Wrap control statements (``if``/``for``/``while``/``switch``/..). 1147 1148 Possible values: 1149 1150 * ``BWACS_Never`` (in configuration: ``Never``) 1151 Never wrap braces after a control statement. 1152 1153 .. code-block:: c++ 1154 1155 if (foo()) { 1156 } else { 1157 } 1158 for (int i = 0; i < 10; ++i) { 1159 } 1160 1161 * ``BWACS_MultiLine`` (in configuration: ``MultiLine``) 1162 Only wrap braces after a multi-line control statement. 1163 1164 .. code-block:: c++ 1165 1166 if (foo && bar && 1167 baz) 1168 { 1169 quux(); 1170 } 1171 while (foo || bar) { 1172 } 1173 1174 * ``BWACS_Always`` (in configuration: ``Always``) 1175 Always wrap braces after a control statement. 1176 1177 .. code-block:: c++ 1178 1179 if (foo()) 1180 { 1181 } else 1182 {} 1183 for (int i = 0; i < 10; ++i) 1184 {} 1185 1186 1187 * ``bool AfterEnum`` Wrap enum definitions. 1188 1189 .. code-block:: c++ 1190 1191 true: 1192 enum X : int 1193 { 1194 B 1195 }; 1196 1197 false: 1198 enum X : int { B }; 1199 1200 * ``bool AfterFunction`` Wrap function definitions. 1201 1202 .. code-block:: c++ 1203 1204 true: 1205 void foo() 1206 { 1207 bar(); 1208 bar2(); 1209 } 1210 1211 false: 1212 void foo() { 1213 bar(); 1214 bar2(); 1215 } 1216 1217 * ``bool AfterNamespace`` Wrap namespace definitions. 1218 1219 .. code-block:: c++ 1220 1221 true: 1222 namespace 1223 { 1224 int foo(); 1225 int bar(); 1226 } 1227 1228 false: 1229 namespace { 1230 int foo(); 1231 int bar(); 1232 } 1233 1234 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). 1235 @autoreleasepool and @synchronized blocks are wrapped 1236 according to `AfterControlStatement` flag. 1237 1238 * ``bool AfterStruct`` Wrap struct definitions. 1239 1240 .. code-block:: c++ 1241 1242 true: 1243 struct foo 1244 { 1245 int x; 1246 }; 1247 1248 false: 1249 struct foo { 1250 int x; 1251 }; 1252 1253 * ``bool AfterUnion`` Wrap union definitions. 1254 1255 .. code-block:: c++ 1256 1257 true: 1258 union foo 1259 { 1260 int x; 1261 } 1262 1263 false: 1264 union foo { 1265 int x; 1266 } 1267 1268 * ``bool AfterExternBlock`` Wrap extern blocks. 1269 1270 .. code-block:: c++ 1271 1272 true: 1273 extern "C" 1274 { 1275 int foo(); 1276 } 1277 1278 false: 1279 extern "C" { 1280 int foo(); 1281 } 1282 1283 * ``bool BeforeCatch`` Wrap before ``catch``. 1284 1285 .. code-block:: c++ 1286 1287 true: 1288 try { 1289 foo(); 1290 } 1291 catch () { 1292 } 1293 1294 false: 1295 try { 1296 foo(); 1297 } catch () { 1298 } 1299 1300 * ``bool BeforeElse`` Wrap before ``else``. 1301 1302 .. code-block:: c++ 1303 1304 true: 1305 if (foo()) { 1306 } 1307 else { 1308 } 1309 1310 false: 1311 if (foo()) { 1312 } else { 1313 } 1314 1315 * ``bool BeforeLambdaBody`` Wrap lambda block. 1316 1317 .. code-block:: c++ 1318 1319 true: 1320 connect( 1321 []() 1322 { 1323 foo(); 1324 bar(); 1325 }); 1326 1327 false: 1328 connect([]() { 1329 foo(); 1330 bar(); 1331 }); 1332 1333 * ``bool BeforeWhile`` Wrap before ``while``. 1334 1335 .. code-block:: c++ 1336 1337 true: 1338 do { 1339 foo(); 1340 } 1341 while (1); 1342 1343 false: 1344 do { 1345 foo(); 1346 } while (1); 1347 1348 * ``bool IndentBraces`` Indent the wrapped braces themselves. 1349 1350 * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line. 1351 This option is used only if the opening brace of the function has 1352 already been wrapped, i.e. the `AfterFunction` brace wrapping mode is 1353 set, and the function could/should not be put on a single line (as per 1354 `AllowShortFunctionsOnASingleLine` and constructor formatting options). 1355 1356 .. code-block:: c++ 1357 1358 int f() vs. int f() 1359 {} { 1360 } 1361 1362 * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body 1363 can be put on a single line. This option is used only if the opening 1364 brace of the record has already been wrapped, i.e. the `AfterClass` 1365 (for classes) brace wrapping mode is set. 1366 1367 .. code-block:: c++ 1368 1369 class Foo vs. class Foo 1370 {} { 1371 } 1372 1373 * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line. 1374 This option is used only if the opening brace of the namespace has 1375 already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is 1376 set. 1377 1378 .. code-block:: c++ 1379 1380 namespace Foo vs. namespace Foo 1381 {} { 1382 } 1383 1384 1385**BreakAfterJavaFieldAnnotations** (``bool``) 1386 Break after each annotation on a field in Java files. 1387 1388 .. code-block:: java 1389 1390 true: false: 1391 @Partial vs. @Partial @Mock DataLoad loader; 1392 @Mock 1393 DataLoad loader; 1394 1395**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) 1396 The way to wrap binary operators. 1397 1398 Possible values: 1399 1400 * ``BOS_None`` (in configuration: ``None``) 1401 Break after operators. 1402 1403 .. code-block:: c++ 1404 1405 LooooooooooongType loooooooooooooooooooooongVariable = 1406 someLooooooooooooooooongFunction(); 1407 1408 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + 1409 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == 1410 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && 1411 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > 1412 ccccccccccccccccccccccccccccccccccccccccc; 1413 1414 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) 1415 Break before operators that aren't assignments. 1416 1417 .. code-block:: c++ 1418 1419 LooooooooooongType loooooooooooooooooooooongVariable = 1420 someLooooooooooooooooongFunction(); 1421 1422 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1423 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1424 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1425 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1426 > ccccccccccccccccccccccccccccccccccccccccc; 1427 1428 * ``BOS_All`` (in configuration: ``All``) 1429 Break before operators. 1430 1431 .. code-block:: c++ 1432 1433 LooooooooooongType loooooooooooooooooooooongVariable 1434 = someLooooooooooooooooongFunction(); 1435 1436 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1437 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1438 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1439 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1440 > ccccccccccccccccccccccccccccccccccccccccc; 1441 1442 1443 1444**BreakBeforeBraces** (``BraceBreakingStyle``) 1445 The brace breaking style to use. 1446 1447 Possible values: 1448 1449 * ``BS_Attach`` (in configuration: ``Attach``) 1450 Always attach braces to surrounding context. 1451 1452 .. code-block:: c++ 1453 1454 namespace N { 1455 enum E { 1456 E1, 1457 E2, 1458 }; 1459 1460 class C { 1461 public: 1462 C(); 1463 }; 1464 1465 bool baz(int i) { 1466 try { 1467 do { 1468 switch (i) { 1469 case 1: { 1470 foobar(); 1471 break; 1472 } 1473 default: { 1474 break; 1475 } 1476 } 1477 } while (--i); 1478 return true; 1479 } catch (...) { 1480 handleError(); 1481 return false; 1482 } 1483 } 1484 1485 void foo(bool b) { 1486 if (b) { 1487 baz(2); 1488 } else { 1489 baz(5); 1490 } 1491 } 1492 1493 void bar() { foo(true); } 1494 } // namespace N 1495 1496 * ``BS_Linux`` (in configuration: ``Linux``) 1497 Like ``Attach``, but break before braces on function, namespace and 1498 class definitions. 1499 1500 .. code-block:: c++ 1501 1502 namespace N 1503 { 1504 enum E { 1505 E1, 1506 E2, 1507 }; 1508 1509 class C 1510 { 1511 public: 1512 C(); 1513 }; 1514 1515 bool baz(int i) 1516 { 1517 try { 1518 do { 1519 switch (i) { 1520 case 1: { 1521 foobar(); 1522 break; 1523 } 1524 default: { 1525 break; 1526 } 1527 } 1528 } while (--i); 1529 return true; 1530 } catch (...) { 1531 handleError(); 1532 return false; 1533 } 1534 } 1535 1536 void foo(bool b) 1537 { 1538 if (b) { 1539 baz(2); 1540 } else { 1541 baz(5); 1542 } 1543 } 1544 1545 void bar() { foo(true); } 1546 } // namespace N 1547 1548 * ``BS_Mozilla`` (in configuration: ``Mozilla``) 1549 Like ``Attach``, but break before braces on enum, function, and record 1550 definitions. 1551 1552 .. code-block:: c++ 1553 1554 namespace N { 1555 enum E 1556 { 1557 E1, 1558 E2, 1559 }; 1560 1561 class C 1562 { 1563 public: 1564 C(); 1565 }; 1566 1567 bool baz(int i) 1568 { 1569 try { 1570 do { 1571 switch (i) { 1572 case 1: { 1573 foobar(); 1574 break; 1575 } 1576 default: { 1577 break; 1578 } 1579 } 1580 } while (--i); 1581 return true; 1582 } catch (...) { 1583 handleError(); 1584 return false; 1585 } 1586 } 1587 1588 void foo(bool b) 1589 { 1590 if (b) { 1591 baz(2); 1592 } else { 1593 baz(5); 1594 } 1595 } 1596 1597 void bar() { foo(true); } 1598 } // namespace N 1599 1600 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) 1601 Like ``Attach``, but break before function definitions, ``catch``, and 1602 ``else``. 1603 1604 .. code-block:: c++ 1605 1606 namespace N { 1607 enum E { 1608 E1, 1609 E2, 1610 }; 1611 1612 class C { 1613 public: 1614 C(); 1615 }; 1616 1617 bool baz(int i) 1618 { 1619 try { 1620 do { 1621 switch (i) { 1622 case 1: { 1623 foobar(); 1624 break; 1625 } 1626 default: { 1627 break; 1628 } 1629 } 1630 } while (--i); 1631 return true; 1632 } 1633 catch (...) { 1634 handleError(); 1635 return false; 1636 } 1637 } 1638 1639 void foo(bool b) 1640 { 1641 if (b) { 1642 baz(2); 1643 } 1644 else { 1645 baz(5); 1646 } 1647 } 1648 1649 void bar() { foo(true); } 1650 } // namespace N 1651 1652 * ``BS_Allman`` (in configuration: ``Allman``) 1653 Always break before braces. 1654 1655 .. code-block:: c++ 1656 1657 namespace N 1658 { 1659 enum E 1660 { 1661 E1, 1662 E2, 1663 }; 1664 1665 class C 1666 { 1667 public: 1668 C(); 1669 }; 1670 1671 bool baz(int i) 1672 { 1673 try 1674 { 1675 do 1676 { 1677 switch (i) 1678 { 1679 case 1: 1680 { 1681 foobar(); 1682 break; 1683 } 1684 default: 1685 { 1686 break; 1687 } 1688 } 1689 } while (--i); 1690 return true; 1691 } 1692 catch (...) 1693 { 1694 handleError(); 1695 return false; 1696 } 1697 } 1698 1699 void foo(bool b) 1700 { 1701 if (b) 1702 { 1703 baz(2); 1704 } 1705 else 1706 { 1707 baz(5); 1708 } 1709 } 1710 1711 void bar() { foo(true); } 1712 } // namespace N 1713 1714 * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``) 1715 Like ``Allman`` but always indent braces and line up code with braces. 1716 1717 .. code-block:: c++ 1718 1719 namespace N 1720 { 1721 enum E 1722 { 1723 E1, 1724 E2, 1725 }; 1726 1727 class C 1728 { 1729 public: 1730 C(); 1731 }; 1732 1733 bool baz(int i) 1734 { 1735 try 1736 { 1737 do 1738 { 1739 switch (i) 1740 { 1741 case 1: 1742 { 1743 foobar(); 1744 break; 1745 } 1746 default: 1747 { 1748 break; 1749 } 1750 } 1751 } while (--i); 1752 return true; 1753 } 1754 catch (...) 1755 { 1756 handleError(); 1757 return false; 1758 } 1759 } 1760 1761 void foo(bool b) 1762 { 1763 if (b) 1764 { 1765 baz(2); 1766 } 1767 else 1768 { 1769 baz(5); 1770 } 1771 } 1772 1773 void bar() { foo(true); } 1774 } // namespace N 1775 1776 * ``BS_GNU`` (in configuration: ``GNU``) 1777 Always break before braces and add an extra level of indentation to 1778 braces of control statements, not to those of class, function 1779 or other definitions. 1780 1781 .. code-block:: c++ 1782 1783 namespace N 1784 { 1785 enum E 1786 { 1787 E1, 1788 E2, 1789 }; 1790 1791 class C 1792 { 1793 public: 1794 C(); 1795 }; 1796 1797 bool baz(int i) 1798 { 1799 try 1800 { 1801 do 1802 { 1803 switch (i) 1804 { 1805 case 1: 1806 { 1807 foobar(); 1808 break; 1809 } 1810 default: 1811 { 1812 break; 1813 } 1814 } 1815 } 1816 while (--i); 1817 return true; 1818 } 1819 catch (...) 1820 { 1821 handleError(); 1822 return false; 1823 } 1824 } 1825 1826 void foo(bool b) 1827 { 1828 if (b) 1829 { 1830 baz(2); 1831 } 1832 else 1833 { 1834 baz(5); 1835 } 1836 } 1837 1838 void bar() { foo(true); } 1839 } // namespace N 1840 1841 * ``BS_WebKit`` (in configuration: ``WebKit``) 1842 Like ``Attach``, but break before functions. 1843 1844 .. code-block:: c++ 1845 1846 namespace N { 1847 enum E { 1848 E1, 1849 E2, 1850 }; 1851 1852 class C { 1853 public: 1854 C(); 1855 }; 1856 1857 bool baz(int i) 1858 { 1859 try { 1860 do { 1861 switch (i) { 1862 case 1: { 1863 foobar(); 1864 break; 1865 } 1866 default: { 1867 break; 1868 } 1869 } 1870 } while (--i); 1871 return true; 1872 } catch (...) { 1873 handleError(); 1874 return false; 1875 } 1876 } 1877 1878 void foo(bool b) 1879 { 1880 if (b) { 1881 baz(2); 1882 } else { 1883 baz(5); 1884 } 1885 } 1886 1887 void bar() { foo(true); } 1888 } // namespace N 1889 1890 * ``BS_Custom`` (in configuration: ``Custom``) 1891 Configure each individual brace in `BraceWrapping`. 1892 1893 1894 1895**BreakBeforeConceptDeclarations** (``bool``) 1896 If ``true``, concept will be placed on a new line. 1897 1898 .. code-block:: c++ 1899 1900 true: 1901 template<typename T> 1902 concept ... 1903 1904 false: 1905 template<typename T> concept ... 1906 1907**BreakBeforeTernaryOperators** (``bool``) 1908 If ``true``, ternary operators will be placed after line breaks. 1909 1910 .. code-block:: c++ 1911 1912 true: 1913 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription 1914 ? firstValue 1915 : SecondValueVeryVeryVeryVeryLong; 1916 1917 false: 1918 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? 1919 firstValue : 1920 SecondValueVeryVeryVeryVeryLong; 1921 1922**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) 1923 The constructor initializers style to use. 1924 1925 Possible values: 1926 1927 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) 1928 Break constructor initializers before the colon and after the commas. 1929 1930 .. code-block:: c++ 1931 1932 Constructor() 1933 : initializer1(), 1934 initializer2() 1935 1936 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) 1937 Break constructor initializers before the colon and commas, and align 1938 the commas with the colon. 1939 1940 .. code-block:: c++ 1941 1942 Constructor() 1943 : initializer1() 1944 , initializer2() 1945 1946 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) 1947 Break constructor initializers after the colon and commas. 1948 1949 .. code-block:: c++ 1950 1951 Constructor() : 1952 initializer1(), 1953 initializer2() 1954 1955 1956 1957**BreakInheritanceList** (``BreakInheritanceListStyle``) 1958 The inheritance list style to use. 1959 1960 Possible values: 1961 1962 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) 1963 Break inheritance list before the colon and after the commas. 1964 1965 .. code-block:: c++ 1966 1967 class Foo 1968 : Base1, 1969 Base2 1970 {}; 1971 1972 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) 1973 Break inheritance list before the colon and commas, and align 1974 the commas with the colon. 1975 1976 .. code-block:: c++ 1977 1978 class Foo 1979 : Base1 1980 , Base2 1981 {}; 1982 1983 * ``BILS_AfterColon`` (in configuration: ``AfterColon``) 1984 Break inheritance list after the colon and commas. 1985 1986 .. code-block:: c++ 1987 1988 class Foo : 1989 Base1, 1990 Base2 1991 {}; 1992 1993 1994 1995**BreakStringLiterals** (``bool``) 1996 Allow breaking string literals when formatting. 1997 1998 .. code-block:: c++ 1999 2000 true: 2001 const char* x = "veryVeryVeryVeryVeryVe" 2002 "ryVeryVeryVeryVeryVery" 2003 "VeryLongString"; 2004 2005 false: 2006 const char* x = 2007 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; 2008 2009**ColumnLimit** (``unsigned``) 2010 The column limit. 2011 2012 A column limit of ``0`` means that there is no column limit. In this case, 2013 clang-format will respect the input's line breaking decisions within 2014 statements unless they contradict other rules. 2015 2016**CommentPragmas** (``std::string``) 2017 A regular expression that describes comments with special meaning, 2018 which should not be split into lines or otherwise changed. 2019 2020 .. code-block:: c++ 2021 2022 // CommentPragmas: '^ FOOBAR pragma:' 2023 // Will leave the following line unaffected 2024 #include <vector> // FOOBAR pragma: keep 2025 2026**CompactNamespaces** (``bool``) 2027 If ``true``, consecutive namespace declarations will be on the same 2028 line. If ``false``, each namespace is declared on a new line. 2029 2030 .. code-block:: c++ 2031 2032 true: 2033 namespace Foo { namespace Bar { 2034 }} 2035 2036 false: 2037 namespace Foo { 2038 namespace Bar { 2039 } 2040 } 2041 2042 If it does not fit on a single line, the overflowing namespaces get 2043 wrapped: 2044 2045 .. code-block:: c++ 2046 2047 namespace Foo { namespace Bar { 2048 namespace Extra { 2049 }}} 2050 2051**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) 2052 If the constructor initializers don't fit on a line, put each 2053 initializer on its own line. 2054 2055 .. code-block:: c++ 2056 2057 true: 2058 SomeClass::Constructor() 2059 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 2060 return 0; 2061 } 2062 2063 false: 2064 SomeClass::Constructor() 2065 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), 2066 aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 2067 return 0; 2068 } 2069 2070**ConstructorInitializerIndentWidth** (``unsigned``) 2071 The number of characters to use for indentation of constructor 2072 initializer lists as well as inheritance lists. 2073 2074**ContinuationIndentWidth** (``unsigned``) 2075 Indent width for line continuations. 2076 2077 .. code-block:: c++ 2078 2079 ContinuationIndentWidth: 2 2080 2081 int i = // VeryVeryVeryVeryVeryLongComment 2082 longFunction( // Again a long comment 2083 arg); 2084 2085**Cpp11BracedListStyle** (``bool``) 2086 If ``true``, format braced lists as best suited for C++11 braced 2087 lists. 2088 2089 Important differences: 2090 - No spaces inside the braced list. 2091 - No line break before the closing brace. 2092 - Indentation with the continuation indent, not with the block indent. 2093 2094 Fundamentally, C++11 braced lists are formatted exactly like function 2095 calls would be formatted in their place. If the braced list follows a name 2096 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 2097 the parentheses of a function call with that name. If there is no name, 2098 a zero-length name is assumed. 2099 2100 .. code-block:: c++ 2101 2102 true: false: 2103 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 }; 2104 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} }; 2105 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); 2106 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; 2107 2108**DeriveLineEnding** (``bool``) 2109 Analyze the formatted file for the most used line ending (``\r\n`` 2110 or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived. 2111 2112**DerivePointerAlignment** (``bool``) 2113 If ``true``, analyze the formatted file for the most common 2114 alignment of ``&`` and ``*``. 2115 Pointer and reference alignment styles are going to be updated according 2116 to the preferences found in the file. 2117 ``PointerAlignment`` is then used only as fallback. 2118 2119**DisableFormat** (``bool``) 2120 Disables formatting completely. 2121 2122**EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) 2123 Defines in which cases to put empty line before access modifiers. 2124 2125 Possible values: 2126 2127 * ``ELBAMS_Never`` (in configuration: ``Never``) 2128 Remove all empty lines before access modifiers. 2129 2130 .. code-block:: c++ 2131 2132 struct foo { 2133 private: 2134 int i; 2135 protected: 2136 int j; 2137 /* comment */ 2138 public: 2139 foo() {} 2140 private: 2141 protected: 2142 }; 2143 2144 * ``ELBAMS_Leave`` (in configuration: ``Leave``) 2145 Keep existing empty lines before access modifiers. 2146 2147 * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``) 2148 Add empty line only when access modifier starts a new logical block. 2149 Logical block is a group of one or more member fields or functions. 2150 2151 .. code-block:: c++ 2152 2153 struct foo { 2154 private: 2155 int i; 2156 2157 protected: 2158 int j; 2159 /* comment */ 2160 public: 2161 foo() {} 2162 2163 private: 2164 protected: 2165 }; 2166 2167 * ``ELBAMS_Always`` (in configuration: ``Always``) 2168 Always add empty line before access modifiers unless access modifier 2169 is at the start of struct or class definition. 2170 2171 .. code-block:: c++ 2172 2173 struct foo { 2174 private: 2175 int i; 2176 2177 protected: 2178 int j; 2179 /* comment */ 2180 2181 public: 2182 foo() {} 2183 2184 private: 2185 2186 protected: 2187 }; 2188 2189 2190 2191**ExperimentalAutoDetectBinPacking** (``bool``) 2192 If ``true``, clang-format detects whether function calls and 2193 definitions are formatted with one parameter per line. 2194 2195 Each call can be bin-packed, one-per-line or inconclusive. If it is 2196 inconclusive, e.g. completely on one line, but a decision needs to be 2197 made, clang-format analyzes whether there are other bin-packed cases in 2198 the input file and act accordingly. 2199 2200 NOTE: This is an experimental flag, that might go away or be renamed. Do 2201 not use this in config files, etc. Use at your own risk. 2202 2203**FixNamespaceComments** (``bool``) 2204 If ``true``, clang-format adds missing namespace end comments and 2205 fixes invalid existing ones. 2206 2207 .. code-block:: c++ 2208 2209 true: false: 2210 namespace a { vs. namespace a { 2211 foo(); foo(); 2212 } // namespace a } 2213 2214**ForEachMacros** (``std::vector<std::string>``) 2215 A vector of macros that should be interpreted as foreach loops 2216 instead of as function calls. 2217 2218 These are expected to be macros of the form: 2219 2220 .. code-block:: c++ 2221 2222 FOREACH(<variable-declaration>, ...) 2223 <loop-body> 2224 2225 In the .clang-format configuration file, this can be configured like: 2226 2227 .. code-block:: yaml 2228 2229 ForEachMacros: ['RANGES_FOR', 'FOREACH'] 2230 2231 For example: BOOST_FOREACH. 2232 2233**IncludeBlocks** (``IncludeBlocksStyle``) 2234 Dependent on the value, multiple ``#include`` blocks can be sorted 2235 as one and divided based on category. 2236 2237 Possible values: 2238 2239 * ``IBS_Preserve`` (in configuration: ``Preserve``) 2240 Sort each ``#include`` block separately. 2241 2242 .. code-block:: c++ 2243 2244 #include "b.h" into #include "b.h" 2245 2246 #include <lib/main.h> #include "a.h" 2247 #include "a.h" #include <lib/main.h> 2248 2249 * ``IBS_Merge`` (in configuration: ``Merge``) 2250 Merge multiple ``#include`` blocks together and sort as one. 2251 2252 .. code-block:: c++ 2253 2254 #include "b.h" into #include "a.h" 2255 #include "b.h" 2256 #include <lib/main.h> #include <lib/main.h> 2257 #include "a.h" 2258 2259 * ``IBS_Regroup`` (in configuration: ``Regroup``) 2260 Merge multiple ``#include`` blocks together and sort as one. 2261 Then split into groups based on category priority. See 2262 ``IncludeCategories``. 2263 2264 .. code-block:: c++ 2265 2266 #include "b.h" into #include "a.h" 2267 #include "b.h" 2268 #include <lib/main.h> 2269 #include "a.h" #include <lib/main.h> 2270 2271 2272 2273**IncludeCategories** (``std::vector<IncludeCategory>``) 2274 Regular expressions denoting the different ``#include`` categories 2275 used for ordering ``#includes``. 2276 2277 `POSIX extended 2278 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ 2279 regular expressions are supported. 2280 2281 These regular expressions are matched against the filename of an include 2282 (including the <> or "") in order. The value belonging to the first 2283 matching regular expression is assigned and ``#includes`` are sorted first 2284 according to increasing category number and then alphabetically within 2285 each category. 2286 2287 If none of the regular expressions match, INT_MAX is assigned as 2288 category. The main header for a source file automatically gets category 0. 2289 so that it is generally kept at the beginning of the ``#includes`` 2290 (https://llvm.org/docs/CodingStandards.html#include-style). However, you 2291 can also assign negative priorities if you have certain headers that 2292 always need to be first. 2293 2294 There is a third and optional field ``SortPriority`` which can used while 2295 ``IncludeBlocks = IBS_Regroup`` to define the priority in which 2296 ``#includes`` should be ordered. The value of ``Priority`` defines the 2297 order of ``#include blocks`` and also allows the grouping of ``#includes`` 2298 of different priority. ``SortPriority`` is set to the value of 2299 ``Priority`` as default if it is not assigned. 2300 2301 Each regular expression can be marked as case sensitive with the field 2302 ``CaseSensitive``, per default it is not. 2303 2304 To configure this in the .clang-format file, use: 2305 2306 .. code-block:: yaml 2307 2308 IncludeCategories: 2309 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 2310 Priority: 2 2311 SortPriority: 2 2312 CaseSensitive: true 2313 - Regex: '^(<|"(gtest|gmock|isl|json)/)' 2314 Priority: 3 2315 - Regex: '<[[:alnum:].]+>' 2316 Priority: 4 2317 - Regex: '.*' 2318 Priority: 1 2319 SortPriority: 0 2320 2321**IncludeIsMainRegex** (``std::string``) 2322 Specify a regular expression of suffixes that are allowed in the 2323 file-to-main-include mapping. 2324 2325 When guessing whether a #include is the "main" include (to assign 2326 category 0, see above), use this regex of allowed suffixes to the header 2327 stem. A partial match is done, so that: 2328 - "" means "arbitrary suffix" 2329 - "$" means "no suffix" 2330 2331 For example, if configured to "(_test)?$", then a header a.h would be seen 2332 as the "main" include in both a.cc and a_test.cc. 2333 2334**IncludeIsMainSourceRegex** (``std::string``) 2335 Specify a regular expression for files being formatted 2336 that are allowed to be considered "main" in the 2337 file-to-main-include mapping. 2338 2339 By default, clang-format considers files as "main" only when they end 2340 with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm`` 2341 extensions. 2342 For these files a guessing of "main" include takes place 2343 (to assign category 0, see above). This config option allows for 2344 additional suffixes and extensions for files to be considered as "main". 2345 2346 For example, if this option is configured to ``(Impl\.hpp)$``, 2347 then a file ``ClassImpl.hpp`` is considered "main" (in addition to 2348 ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main 2349 include file" logic will be executed (with *IncludeIsMainRegex* setting 2350 also being respected in later phase). Without this option set, 2351 ``ClassImpl.hpp`` would not have the main include file put on top 2352 before any other include. 2353 2354**IndentCaseBlocks** (``bool``) 2355 Indent case label blocks one level from the case label. 2356 2357 When ``false``, the block following the case label uses the same 2358 indentation level as for the case label, treating the case label the same 2359 as an if-statement. 2360 When ``true``, the block gets indented as a scope block. 2361 2362 .. code-block:: c++ 2363 2364 false: true: 2365 switch (fool) { vs. switch (fool) { 2366 case 1: { case 1: 2367 bar(); { 2368 } break; bar(); 2369 default: { } 2370 plop(); break; 2371 } default: 2372 } { 2373 plop(); 2374 } 2375 } 2376 2377**IndentCaseLabels** (``bool``) 2378 Indent case labels one level from the switch statement. 2379 2380 When ``false``, use the same indentation level as for the switch 2381 statement. Switch statement body is always indented one level more than 2382 case labels (except the first block following the case label, which 2383 itself indents the code - unless IndentCaseBlocks is enabled). 2384 2385 .. code-block:: c++ 2386 2387 false: true: 2388 switch (fool) { vs. switch (fool) { 2389 case 1: case 1: 2390 bar(); bar(); 2391 break; break; 2392 default: default: 2393 plop(); plop(); 2394 } } 2395 2396**IndentExternBlock** (``IndentExternBlockStyle``) 2397 IndentExternBlockStyle is the type of indenting of extern blocks. 2398 2399 Possible values: 2400 2401 * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``) 2402 Backwards compatible with AfterExternBlock's indenting. 2403 2404 .. code-block:: c++ 2405 2406 IndentExternBlock: AfterExternBlock 2407 BraceWrapping.AfterExternBlock: true 2408 extern "C" 2409 { 2410 void foo(); 2411 } 2412 2413 2414 .. code-block:: c++ 2415 2416 IndentExternBlock: AfterExternBlock 2417 BraceWrapping.AfterExternBlock: false 2418 extern "C" { 2419 void foo(); 2420 } 2421 2422 * ``IEBS_NoIndent`` (in configuration: ``NoIndent``) 2423 Does not indent extern blocks. 2424 2425 .. code-block:: c++ 2426 2427 extern "C" { 2428 void foo(); 2429 } 2430 2431 * ``IEBS_Indent`` (in configuration: ``Indent``) 2432 Indents extern blocks. 2433 2434 .. code-block:: c++ 2435 2436 extern "C" { 2437 void foo(); 2438 } 2439 2440 2441 2442**IndentGotoLabels** (``bool``) 2443 Indent goto labels. 2444 2445 When ``false``, goto labels are flushed left. 2446 2447 .. code-block:: c++ 2448 2449 true: false: 2450 int f() { vs. int f() { 2451 if (foo()) { if (foo()) { 2452 label1: label1: 2453 bar(); bar(); 2454 } } 2455 label2: label2: 2456 return 1; return 1; 2457 } } 2458 2459**IndentPPDirectives** (``PPDirectiveIndentStyle``) 2460 The preprocessor directive indenting style to use. 2461 2462 Possible values: 2463 2464 * ``PPDIS_None`` (in configuration: ``None``) 2465 Does not indent any directives. 2466 2467 .. code-block:: c++ 2468 2469 #if FOO 2470 #if BAR 2471 #include <foo> 2472 #endif 2473 #endif 2474 2475 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``) 2476 Indents directives after the hash. 2477 2478 .. code-block:: c++ 2479 2480 #if FOO 2481 # if BAR 2482 # include <foo> 2483 # endif 2484 #endif 2485 2486 * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) 2487 Indents directives before the hash. 2488 2489 .. code-block:: c++ 2490 2491 #if FOO 2492 #if BAR 2493 #include <foo> 2494 #endif 2495 #endif 2496 2497 2498 2499**IndentRequires** (``bool``) 2500 Indent the requires clause in a template 2501 2502 .. code-block:: c++ 2503 2504 true: 2505 template <typename It> 2506 requires Iterator<It> 2507 void sort(It begin, It end) { 2508 //.... 2509 } 2510 2511 false: 2512 template <typename It> 2513 requires Iterator<It> 2514 void sort(It begin, It end) { 2515 //.... 2516 } 2517 2518**IndentWidth** (``unsigned``) 2519 The number of columns to use for indentation. 2520 2521 .. code-block:: c++ 2522 2523 IndentWidth: 3 2524 2525 void f() { 2526 someFunction(); 2527 if (true, false) { 2528 f(); 2529 } 2530 } 2531 2532**IndentWrappedFunctionNames** (``bool``) 2533 Indent if a function definition or declaration is wrapped after the 2534 type. 2535 2536 .. code-block:: c++ 2537 2538 true: 2539 LoooooooooooooooooooooooooooooooooooooooongReturnType 2540 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 2541 2542 false: 2543 LoooooooooooooooooooooooooooooooooooooooongReturnType 2544 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 2545 2546**InsertTrailingCommas** (``TrailingCommaStyle``) 2547 If set to ``TCS_Wrapped`` will insert trailing commas in container 2548 literals (arrays and objects) that wrap across multiple lines. 2549 It is currently only available for JavaScript 2550 and disabled by default ``TCS_None``. 2551 ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` 2552 as inserting the comma disables bin-packing. 2553 2554 .. code-block:: c++ 2555 2556 TSC_Wrapped: 2557 const someArray = [ 2558 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2559 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2560 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2561 // ^ inserted 2562 ] 2563 2564 Possible values: 2565 2566 * ``TCS_None`` (in configuration: ``None``) 2567 Do not insert trailing commas. 2568 2569 * ``TCS_Wrapped`` (in configuration: ``Wrapped``) 2570 Insert trailing commas in container literals that were wrapped over 2571 multiple lines. Note that this is conceptually incompatible with 2572 bin-packing, because the trailing comma is used as an indicator 2573 that a container should be formatted one-per-line (i.e. not bin-packed). 2574 So inserting a trailing comma counteracts bin-packing. 2575 2576 2577 2578**JavaImportGroups** (``std::vector<std::string>``) 2579 A vector of prefixes ordered by the desired groups for Java imports. 2580 2581 One group's prefix can be a subset of another - the longest prefix is 2582 always matched. Within a group, the imports are ordered lexicographically. 2583 Static imports are grouped separately and follow the same group rules. 2584 By default, static imports are placed before non-static imports, 2585 but this behavior is changed by another option, 2586 ``SortJavaStaticImport``. 2587 2588 In the .clang-format configuration file, this can be configured like 2589 in the following yaml example. This will result in imports being 2590 formatted as in the Java example below. 2591 2592 .. code-block:: yaml 2593 2594 JavaImportGroups: ['com.example', 'com', 'org'] 2595 2596 2597 .. code-block:: java 2598 2599 import static com.example.function1; 2600 2601 import static com.test.function2; 2602 2603 import static org.example.function3; 2604 2605 import com.example.ClassA; 2606 import com.example.Test; 2607 import com.example.a.ClassB; 2608 2609 import com.test.ClassC; 2610 2611 import org.example.ClassD; 2612 2613**JavaScriptQuotes** (``JavaScriptQuoteStyle``) 2614 The JavaScriptQuoteStyle to use for JavaScript strings. 2615 2616 Possible values: 2617 2618 * ``JSQS_Leave`` (in configuration: ``Leave``) 2619 Leave string quotes as they are. 2620 2621 .. code-block:: js 2622 2623 string1 = "foo"; 2624 string2 = 'bar'; 2625 2626 * ``JSQS_Single`` (in configuration: ``Single``) 2627 Always use single quotes. 2628 2629 .. code-block:: js 2630 2631 string1 = 'foo'; 2632 string2 = 'bar'; 2633 2634 * ``JSQS_Double`` (in configuration: ``Double``) 2635 Always use double quotes. 2636 2637 .. code-block:: js 2638 2639 string1 = "foo"; 2640 string2 = "bar"; 2641 2642 2643 2644**JavaScriptWrapImports** (``bool``) 2645 Whether to wrap JavaScript import/export statements. 2646 2647 .. code-block:: js 2648 2649 true: 2650 import { 2651 VeryLongImportsAreAnnoying, 2652 VeryLongImportsAreAnnoying, 2653 VeryLongImportsAreAnnoying, 2654 } from 'some/module.js' 2655 2656 false: 2657 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" 2658 2659**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) 2660 If true, the empty line at the start of blocks is kept. 2661 2662 .. code-block:: c++ 2663 2664 true: false: 2665 if (foo) { vs. if (foo) { 2666 bar(); 2667 bar(); } 2668 } 2669 2670**Language** (``LanguageKind``) 2671 Language, this format style is targeted at. 2672 2673 Possible values: 2674 2675 * ``LK_None`` (in configuration: ``None``) 2676 Do not use. 2677 2678 * ``LK_Cpp`` (in configuration: ``Cpp``) 2679 Should be used for C, C++. 2680 2681 * ``LK_CSharp`` (in configuration: ``CSharp``) 2682 Should be used for C#. 2683 2684 * ``LK_Java`` (in configuration: ``Java``) 2685 Should be used for Java. 2686 2687 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 2688 Should be used for JavaScript. 2689 2690 * ``LK_ObjC`` (in configuration: ``ObjC``) 2691 Should be used for Objective-C, Objective-C++. 2692 2693 * ``LK_Proto`` (in configuration: ``Proto``) 2694 Should be used for Protocol Buffers 2695 (https://developers.google.com/protocol-buffers/). 2696 2697 * ``LK_TableGen`` (in configuration: ``TableGen``) 2698 Should be used for TableGen code. 2699 2700 * ``LK_TextProto`` (in configuration: ``TextProto``) 2701 Should be used for Protocol Buffer messages in text format 2702 (https://developers.google.com/protocol-buffers/). 2703 2704 2705 2706**MacroBlockBegin** (``std::string``) 2707 A regular expression matching macros that start a block. 2708 2709 .. code-block:: c++ 2710 2711 # With: 2712 MacroBlockBegin: "^NS_MAP_BEGIN|\ 2713 NS_TABLE_HEAD$" 2714 MacroBlockEnd: "^\ 2715 NS_MAP_END|\ 2716 NS_TABLE_.*_END$" 2717 2718 NS_MAP_BEGIN 2719 foo(); 2720 NS_MAP_END 2721 2722 NS_TABLE_HEAD 2723 bar(); 2724 NS_TABLE_FOO_END 2725 2726 # Without: 2727 NS_MAP_BEGIN 2728 foo(); 2729 NS_MAP_END 2730 2731 NS_TABLE_HEAD 2732 bar(); 2733 NS_TABLE_FOO_END 2734 2735**MacroBlockEnd** (``std::string``) 2736 A regular expression matching macros that end a block. 2737 2738**MaxEmptyLinesToKeep** (``unsigned``) 2739 The maximum number of consecutive empty lines to keep. 2740 2741 .. code-block:: c++ 2742 2743 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 2744 int f() { int f() { 2745 int = 1; int i = 1; 2746 i = foo(); 2747 i = foo(); return i; 2748 } 2749 return i; 2750 } 2751 2752**NamespaceIndentation** (``NamespaceIndentationKind``) 2753 The indentation used for namespaces. 2754 2755 Possible values: 2756 2757 * ``NI_None`` (in configuration: ``None``) 2758 Don't indent in namespaces. 2759 2760 .. code-block:: c++ 2761 2762 namespace out { 2763 int i; 2764 namespace in { 2765 int i; 2766 } 2767 } 2768 2769 * ``NI_Inner`` (in configuration: ``Inner``) 2770 Indent only in inner namespaces (nested in other namespaces). 2771 2772 .. code-block:: c++ 2773 2774 namespace out { 2775 int i; 2776 namespace in { 2777 int i; 2778 } 2779 } 2780 2781 * ``NI_All`` (in configuration: ``All``) 2782 Indent in all namespaces. 2783 2784 .. code-block:: c++ 2785 2786 namespace out { 2787 int i; 2788 namespace in { 2789 int i; 2790 } 2791 } 2792 2793 2794 2795**NamespaceMacros** (``std::vector<std::string>``) 2796 A vector of macros which are used to open namespace blocks. 2797 2798 These are expected to be macros of the form: 2799 2800 .. code-block:: c++ 2801 2802 NAMESPACE(<namespace-name>, ...) { 2803 <namespace-content> 2804 } 2805 2806 For example: TESTSUITE 2807 2808**ObjCBinPackProtocolList** (``BinPackStyle``) 2809 Controls bin-packing Objective-C protocol conformance list 2810 items into as few lines as possible when they go over ``ColumnLimit``. 2811 2812 If ``Auto`` (the default), delegates to the value in 2813 ``BinPackParameters``. If that is ``true``, bin-packs Objective-C 2814 protocol conformance list items into as few lines as possible 2815 whenever they go over ``ColumnLimit``. 2816 2817 If ``Always``, always bin-packs Objective-C protocol conformance 2818 list items into as few lines as possible whenever they go over 2819 ``ColumnLimit``. 2820 2821 If ``Never``, lays out Objective-C protocol conformance list items 2822 onto individual lines whenever they go over ``ColumnLimit``. 2823 2824 2825 .. code-block:: objc 2826 2827 Always (or Auto, if BinPackParameters=true): 2828 @interface ccccccccccccc () < 2829 ccccccccccccc, ccccccccccccc, 2830 ccccccccccccc, ccccccccccccc> { 2831 } 2832 2833 Never (or Auto, if BinPackParameters=false): 2834 @interface ddddddddddddd () < 2835 ddddddddddddd, 2836 ddddddddddddd, 2837 ddddddddddddd, 2838 ddddddddddddd> { 2839 } 2840 2841 Possible values: 2842 2843 * ``BPS_Auto`` (in configuration: ``Auto``) 2844 Automatically determine parameter bin-packing behavior. 2845 2846 * ``BPS_Always`` (in configuration: ``Always``) 2847 Always bin-pack parameters. 2848 2849 * ``BPS_Never`` (in configuration: ``Never``) 2850 Never bin-pack parameters. 2851 2852 2853 2854**ObjCBlockIndentWidth** (``unsigned``) 2855 The number of characters to use for indentation of ObjC blocks. 2856 2857 .. code-block:: objc 2858 2859 ObjCBlockIndentWidth: 4 2860 2861 [operation setCompletionBlock:^{ 2862 [self onOperationDone]; 2863 }]; 2864 2865**ObjCBreakBeforeNestedBlockParam** (``bool``) 2866 Break parameters list into lines when there is nested block 2867 parameters in a function call. 2868 2869 .. code-block:: c++ 2870 2871 false: 2872 - (void)_aMethod 2873 { 2874 [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber 2875 *u, NSNumber *v) { 2876 u = c; 2877 }] 2878 } 2879 true: 2880 - (void)_aMethod 2881 { 2882 [self.test1 t:self 2883 w:self 2884 callback:^(typeof(self) self, NSNumber *u, NSNumber *v) { 2885 u = c; 2886 }] 2887 } 2888 2889**ObjCSpaceAfterProperty** (``bool``) 2890 Add a space after ``@property`` in Objective-C, i.e. use 2891 ``@property (readonly)`` instead of ``@property(readonly)``. 2892 2893**ObjCSpaceBeforeProtocolList** (``bool``) 2894 Add a space in front of an Objective-C protocol list, i.e. use 2895 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 2896 2897**PenaltyBreakAssignment** (``unsigned``) 2898 The penalty for breaking around an assignment operator. 2899 2900**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) 2901 The penalty for breaking a function call after ``call(``. 2902 2903**PenaltyBreakComment** (``unsigned``) 2904 The penalty for each line break introduced inside a comment. 2905 2906**PenaltyBreakFirstLessLess** (``unsigned``) 2907 The penalty for breaking before the first ``<<``. 2908 2909**PenaltyBreakString** (``unsigned``) 2910 The penalty for each line break introduced inside a string literal. 2911 2912**PenaltyBreakTemplateDeclaration** (``unsigned``) 2913 The penalty for breaking after template declaration. 2914 2915**PenaltyExcessCharacter** (``unsigned``) 2916 The penalty for each character outside of the column limit. 2917 2918**PenaltyIndentedWhitespace** (``unsigned``) 2919 Penalty for each character of whitespace indentation 2920 (counted relative to leading non-whitespace column). 2921 2922**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) 2923 Penalty for putting the return type of a function onto its own 2924 line. 2925 2926**PointerAlignment** (``PointerAlignmentStyle``) 2927 Pointer and reference alignment style. 2928 2929 Possible values: 2930 2931 * ``PAS_Left`` (in configuration: ``Left``) 2932 Align pointer to the left. 2933 2934 .. code-block:: c++ 2935 2936 int* a; 2937 2938 * ``PAS_Right`` (in configuration: ``Right``) 2939 Align pointer to the right. 2940 2941 .. code-block:: c++ 2942 2943 int *a; 2944 2945 * ``PAS_Middle`` (in configuration: ``Middle``) 2946 Align pointer in the middle. 2947 2948 .. code-block:: c++ 2949 2950 int * a; 2951 2952 2953 2954**RawStringFormats** (``std::vector<RawStringFormat>``) 2955 Defines hints for detecting supported languages code blocks in raw 2956 strings. 2957 2958 A raw string with a matching delimiter or a matching enclosing function 2959 name will be reformatted assuming the specified language based on the 2960 style for that language defined in the .clang-format file. If no style has 2961 been defined in the .clang-format file for the specific language, a 2962 predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not 2963 found, the formatting is based on llvm style. A matching delimiter takes 2964 precedence over a matching enclosing function name for determining the 2965 language of the raw string contents. 2966 2967 If a canonical delimiter is specified, occurrences of other delimiters for 2968 the same language will be updated to the canonical if possible. 2969 2970 There should be at most one specification per language and each delimiter 2971 and enclosing function should not occur in multiple specifications. 2972 2973 To configure this in the .clang-format file, use: 2974 2975 .. code-block:: yaml 2976 2977 RawStringFormats: 2978 - Language: TextProto 2979 Delimiters: 2980 - 'pb' 2981 - 'proto' 2982 EnclosingFunctions: 2983 - 'PARSE_TEXT_PROTO' 2984 BasedOnStyle: google 2985 - Language: Cpp 2986 Delimiters: 2987 - 'cc' 2988 - 'cpp' 2989 BasedOnStyle: llvm 2990 CanonicalDelimiter: 'cc' 2991 2992**ReflowComments** (``bool``) 2993 If ``true``, clang-format will attempt to re-flow comments. 2994 2995 .. code-block:: c++ 2996 2997 false: 2998 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 2999 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 3000 3001 true: 3002 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 3003 // information 3004 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 3005 * information */ 3006 3007**SortIncludes** (``bool``) 3008 If ``true``, clang-format will sort ``#includes``. 3009 3010 .. code-block:: c++ 3011 3012 false: true: 3013 #include "b.h" vs. #include "a.h" 3014 #include "a.h" #include "b.h" 3015 3016**SortJavaStaticImport** (``SortJavaStaticImportOptions``) 3017 When sorting Java imports, by default static imports are placed before 3018 non-static imports. If ``JavaStaticImportAfterImport`` is ``After``, 3019 static imports are placed after non-static imports. 3020 3021 Possible values: 3022 3023 * ``SJSIO_Before`` (in configuration: ``Before``) 3024 Static imports are placed before non-static imports. 3025 3026 .. code-block:: java 3027 3028 import static org.example.function1; 3029 3030 import org.example.ClassA; 3031 3032 * ``SJSIO_After`` (in configuration: ``After``) 3033 Static imports are placed after non-static imports. 3034 3035 .. code-block:: java 3036 3037 import org.example.ClassA; 3038 3039 import static org.example.function1; 3040 3041 3042 3043**SortUsingDeclarations** (``bool``) 3044 If ``true``, clang-format will sort using declarations. 3045 3046 The order of using declarations is defined as follows: 3047 Split the strings by "::" and discard any initial empty strings. The last 3048 element of each list is a non-namespace name; all others are namespace 3049 names. Sort the lists of names lexicographically, where the sort order of 3050 individual names is that all non-namespace names come before all namespace 3051 names, and within those groups, names are in case-insensitive 3052 lexicographic order. 3053 3054 .. code-block:: c++ 3055 3056 false: true: 3057 using std::cout; vs. using std::cin; 3058 using std::cin; using std::cout; 3059 3060**SpaceAfterCStyleCast** (``bool``) 3061 If ``true``, a space is inserted after C style casts. 3062 3063 .. code-block:: c++ 3064 3065 true: false: 3066 (int) i; vs. (int)i; 3067 3068**SpaceAfterLogicalNot** (``bool``) 3069 If ``true``, a space is inserted after the logical not operator (``!``). 3070 3071 .. code-block:: c++ 3072 3073 true: false: 3074 ! someExpression(); vs. !someExpression(); 3075 3076**SpaceAfterTemplateKeyword** (``bool``) 3077 If ``true``, a space will be inserted after the 'template' keyword. 3078 3079 .. code-block:: c++ 3080 3081 true: false: 3082 template <int> void foo(); vs. template<int> void foo(); 3083 3084**SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) 3085 Defines in which cases to put a space before or after pointer qualifiers 3086 3087 Possible values: 3088 3089 * ``SAPQ_Default`` (in configuration: ``Default``) 3090 Don't ensure spaces around pointer qualifiers and use PointerAlignment 3091 instead. 3092 3093 .. code-block:: c++ 3094 3095 PointerAlignment: Left PointerAlignment: Right 3096 void* const* x = NULL; vs. void *const *x = NULL; 3097 3098 * ``SAPQ_Before`` (in configuration: ``Before``) 3099 Ensure that there is a space before pointer qualifiers. 3100 3101 .. code-block:: c++ 3102 3103 PointerAlignment: Left PointerAlignment: Right 3104 void* const* x = NULL; vs. void * const *x = NULL; 3105 3106 * ``SAPQ_After`` (in configuration: ``After``) 3107 Ensure that there is a space after pointer qualifiers. 3108 3109 .. code-block:: c++ 3110 3111 PointerAlignment: Left PointerAlignment: Right 3112 void* const * x = NULL; vs. void *const *x = NULL; 3113 3114 * ``SAPQ_Both`` (in configuration: ``Both``) 3115 Ensure that there is a space both before and after pointer qualifiers. 3116 3117 .. code-block:: c++ 3118 3119 PointerAlignment: Left PointerAlignment: Right 3120 void* const * x = NULL; vs. void * const *x = NULL; 3121 3122 3123 3124**SpaceBeforeAssignmentOperators** (``bool``) 3125 If ``false``, spaces will be removed before assignment operators. 3126 3127 .. code-block:: c++ 3128 3129 true: false: 3130 int a = 5; vs. int a= 5; 3131 a += 42; a+= 42; 3132 3133**SpaceBeforeCaseColon** (``bool``) 3134 If ``false``, spaces will be removed before case colon. 3135 3136 .. code-block:: c++ 3137 3138 true: false 3139 switch (x) { vs. switch (x) { 3140 case 1 : break; case 1: break; 3141 } } 3142 3143**SpaceBeforeCpp11BracedList** (``bool``) 3144 If ``true``, a space will be inserted before a C++11 braced list 3145 used to initialize an object (after the preceding identifier or type). 3146 3147 .. code-block:: c++ 3148 3149 true: false: 3150 Foo foo { bar }; vs. Foo foo{ bar }; 3151 Foo {}; Foo{}; 3152 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; 3153 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; 3154 3155**SpaceBeforeCtorInitializerColon** (``bool``) 3156 If ``false``, spaces will be removed before constructor initializer 3157 colon. 3158 3159 .. code-block:: c++ 3160 3161 true: false: 3162 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} 3163 3164**SpaceBeforeInheritanceColon** (``bool``) 3165 If ``false``, spaces will be removed before inheritance colon. 3166 3167 .. code-block:: c++ 3168 3169 true: false: 3170 class Foo : Bar {} vs. class Foo: Bar {} 3171 3172**SpaceBeforeParens** (``SpaceBeforeParensOptions``) 3173 Defines in which cases to put a space before opening parentheses. 3174 3175 Possible values: 3176 3177 * ``SBPO_Never`` (in configuration: ``Never``) 3178 Never put a space before opening parentheses. 3179 3180 .. code-block:: c++ 3181 3182 void f() { 3183 if(true) { 3184 f(); 3185 } 3186 } 3187 3188 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 3189 Put a space before opening parentheses only after control statement 3190 keywords (``for/if/while...``). 3191 3192 .. code-block:: c++ 3193 3194 void f() { 3195 if (true) { 3196 f(); 3197 } 3198 } 3199 3200 * ``SBPO_ControlStatementsExceptForEachMacros`` (in configuration: ``ControlStatementsExceptForEachMacros``) 3201 Same as ``SBPO_ControlStatements`` except this option doesn't apply to 3202 ForEach macros. This is useful in projects where ForEach macros are 3203 treated as function calls instead of control statements. 3204 3205 .. code-block:: c++ 3206 3207 void f() { 3208 Q_FOREACH(...) { 3209 f(); 3210 } 3211 } 3212 3213 * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``) 3214 Put a space before opening parentheses only if the parentheses are not 3215 empty i.e. '()' 3216 3217 .. code-block:: c++ 3218 3219 void() { 3220 if (true) { 3221 f(); 3222 g (x, y, z); 3223 } 3224 } 3225 3226 * ``SBPO_Always`` (in configuration: ``Always``) 3227 Always put a space before opening parentheses, except when it's 3228 prohibited by the syntax rules (in function-like macro definitions) or 3229 when determined by other style rules (after unary operators, opening 3230 parentheses, etc.) 3231 3232 .. code-block:: c++ 3233 3234 void f () { 3235 if (true) { 3236 f (); 3237 } 3238 } 3239 3240 3241 3242**SpaceBeforeRangeBasedForLoopColon** (``bool``) 3243 If ``false``, spaces will be removed before range-based for loop 3244 colon. 3245 3246 .. code-block:: c++ 3247 3248 true: false: 3249 for (auto v : values) {} vs. for(auto v: values) {} 3250 3251**SpaceBeforeSquareBrackets** (``bool``) 3252 If ``true``, spaces will be before ``[``. 3253 Lambdas will not be affected. Only the first ``[`` will get a space added. 3254 3255 .. code-block:: c++ 3256 3257 true: false: 3258 int a [5]; vs. int a[5]; 3259 int a [5][5]; vs. int a[5][5]; 3260 3261**SpaceInEmptyBlock** (``bool``) 3262 If ``true``, spaces will be inserted into ``{}``. 3263 3264 .. code-block:: c++ 3265 3266 true: false: 3267 void f() { } vs. void f() {} 3268 while (true) { } while (true) {} 3269 3270**SpaceInEmptyParentheses** (``bool``) 3271 If ``true``, spaces may be inserted into ``()``. 3272 3273 .. code-block:: c++ 3274 3275 true: false: 3276 void f( ) { vs. void f() { 3277 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; 3278 if (true) { if (true) { 3279 f( ); f(); 3280 } } 3281 } } 3282 3283**SpacesBeforeTrailingComments** (``unsigned``) 3284 The number of spaces before trailing line comments 3285 (``//`` - comments). 3286 3287 This does not affect trailing block comments (``/*`` - comments) as 3288 those commonly have different usage patterns and a number of special 3289 cases. 3290 3291 .. code-block:: c++ 3292 3293 SpacesBeforeTrailingComments: 3 3294 void f() { 3295 if (true) { // foo1 3296 f(); // bar 3297 } // foo 3298 } 3299 3300**SpacesInAngles** (``bool``) 3301 If ``true``, spaces will be inserted after ``<`` and before ``>`` 3302 in template argument lists. 3303 3304 .. code-block:: c++ 3305 3306 true: false: 3307 static_cast< int >(arg); vs. static_cast<int>(arg); 3308 std::function< void(int) > fct; std::function<void(int)> fct; 3309 3310**SpacesInCStyleCastParentheses** (``bool``) 3311 If ``true``, spaces may be inserted into C style casts. 3312 3313 .. code-block:: c++ 3314 3315 true: false: 3316 x = ( int32 )y vs. x = (int32)y 3317 3318**SpacesInConditionalStatement** (``bool``) 3319 If ``true``, spaces will be inserted around if/for/switch/while 3320 conditions. 3321 3322 .. code-block:: c++ 3323 3324 true: false: 3325 if ( a ) { ... } vs. if (a) { ... } 3326 while ( i < 5 ) { ... } while (i < 5) { ... } 3327 3328**SpacesInContainerLiterals** (``bool``) 3329 If ``true``, spaces are inserted inside container literals (e.g. 3330 ObjC and Javascript array and dict literals). 3331 3332 .. code-block:: js 3333 3334 true: false: 3335 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; 3336 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); 3337 3338**SpacesInParentheses** (``bool``) 3339 If ``true``, spaces will be inserted after ``(`` and before ``)``. 3340 3341 .. code-block:: c++ 3342 3343 true: false: 3344 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; 3345 3346**SpacesInSquareBrackets** (``bool``) 3347 If ``true``, spaces will be inserted after ``[`` and before ``]``. 3348 Lambdas without arguments or unspecified size array declarations will not 3349 be affected. 3350 3351 .. code-block:: c++ 3352 3353 true: false: 3354 int a[ 5 ]; vs. int a[5]; 3355 std::unique_ptr<int[]> foo() {} // Won't be affected 3356 3357**Standard** (``LanguageStandard``) 3358 Parse and format C++ constructs compatible with this standard. 3359 3360 .. code-block:: c++ 3361 3362 c++03: latest: 3363 vector<set<int> > x; vs. vector<set<int>> x; 3364 3365 Possible values: 3366 3367 * ``LS_Cpp03`` (in configuration: ``c++03``) 3368 Parse and format as C++03. 3369 ``Cpp03`` is a deprecated alias for ``c++03`` 3370 3371 * ``LS_Cpp11`` (in configuration: ``c++11``) 3372 Parse and format as C++11. 3373 3374 * ``LS_Cpp14`` (in configuration: ``c++14``) 3375 Parse and format as C++14. 3376 3377 * ``LS_Cpp17`` (in configuration: ``c++17``) 3378 Parse and format as C++17. 3379 3380 * ``LS_Cpp20`` (in configuration: ``c++20``) 3381 Parse and format as C++20. 3382 3383 * ``LS_Latest`` (in configuration: ``Latest``) 3384 Parse and format using the latest supported language version. 3385 ``Cpp11`` is a deprecated alias for ``Latest`` 3386 3387 * ``LS_Auto`` (in configuration: ``Auto``) 3388 Automatic detection based on the input. 3389 3390 3391 3392**StatementAttributeLikeMacros** (``std::vector<std::string>``) 3393 Macros which are ignored in front of a statement, as if they were an 3394 attribute. So that they are not parsed as identifier, for example for Qts 3395 emit. 3396 3397 .. code-block:: c++ 3398 3399 AlignConsecutiveDeclarations: true 3400 StatementAttributeLikeMacros: [] 3401 unsigned char data = 'x'; 3402 emit signal(data); // This is parsed as variable declaration. 3403 3404 AlignConsecutiveDeclarations: true 3405 StatementAttributeLikeMacros: [emit] 3406 unsigned char data = 'x'; 3407 emit signal(data); // Now it's fine again. 3408 3409**StatementMacros** (``std::vector<std::string>``) 3410 A vector of macros that should be interpreted as complete 3411 statements. 3412 3413 Typical macros are expressions, and require a semi-colon to be 3414 added; sometimes this is not the case, and this allows to make 3415 clang-format aware of such cases. 3416 3417 For example: Q_UNUSED 3418 3419**TabWidth** (``unsigned``) 3420 The number of columns used for tab stops. 3421 3422**TypenameMacros** (``std::vector<std::string>``) 3423 A vector of macros that should be interpreted as type declarations 3424 instead of as function calls. 3425 3426 These are expected to be macros of the form: 3427 3428 .. code-block:: c++ 3429 3430 STACK_OF(...) 3431 3432 In the .clang-format configuration file, this can be configured like: 3433 3434 .. code-block:: yaml 3435 3436 TypenameMacros: ['STACK_OF', 'LIST'] 3437 3438 For example: OpenSSL STACK_OF, BSD LIST_ENTRY. 3439 3440**UseCRLF** (``bool``) 3441 Use ``\r\n`` instead of ``\n`` for line breaks. 3442 Also used as fallback if ``DeriveLineEnding`` is true. 3443 3444**UseTab** (``UseTabStyle``) 3445 The way to use tab characters in the resulting file. 3446 3447 Possible values: 3448 3449 * ``UT_Never`` (in configuration: ``Never``) 3450 Never use tab. 3451 3452 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 3453 Use tabs only for indentation. 3454 3455 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``) 3456 Fill all leading whitespace with tabs, and use spaces for alignment that 3457 appears within a line (e.g. consecutive assignments and declarations). 3458 3459 * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``) 3460 Use tabs for line continuation and indentation, and spaces for 3461 alignment. 3462 3463 * ``UT_Always`` (in configuration: ``Always``) 3464 Use tabs whenever we need to fill whitespace that spans at least from 3465 one tab stop to the next one. 3466 3467 3468 3469**WhitespaceSensitiveMacros** (``std::vector<std::string>``) 3470 A vector of macros which are whitespace-sensitive and should not 3471 be touched. 3472 3473 These are expected to be macros of the form: 3474 3475 .. code-block:: c++ 3476 3477 STRINGIZE(...) 3478 3479 In the .clang-format configuration file, this can be configured like: 3480 3481 .. code-block:: yaml 3482 3483 WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE'] 3484 3485 For example: BOOST_PP_STRINGIZE 3486 3487.. END_FORMAT_STYLE_OPTIONS 3488 3489Adding additional style options 3490=============================== 3491 3492Each additional style option adds costs to the clang-format project. Some of 3493these costs affect the clang-format development itself, as we need to make 3494sure that any given combination of options work and that new features don't 3495break any of the existing options in any way. There are also costs for end users 3496as options become less discoverable and people have to think about and make a 3497decision on options they don't really care about. 3498 3499The goal of the clang-format project is more on the side of supporting a 3500limited set of styles really well as opposed to supporting every single style 3501used by a codebase somewhere in the wild. Of course, we do want to support all 3502major projects and thus have established the following bar for adding style 3503options. Each new style option must .. 3504 3505 * be used in a project of significant size (have dozens of contributors) 3506 * have a publicly accessible style guide 3507 * have a person willing to contribute and maintain patches 3508 3509Examples 3510======== 3511 3512A style similar to the `Linux Kernel style 3513<https://www.kernel.org/doc/Documentation/CodingStyle>`_: 3514 3515.. code-block:: yaml 3516 3517 BasedOnStyle: LLVM 3518 IndentWidth: 8 3519 UseTab: Always 3520 BreakBeforeBraces: Linux 3521 AllowShortIfStatementsOnASingleLine: false 3522 IndentCaseLabels: false 3523 3524The result is (imagine that tabs are used for indentation here): 3525 3526.. code-block:: c++ 3527 3528 void test() 3529 { 3530 switch (x) { 3531 case 0: 3532 case 1: 3533 do_something(); 3534 break; 3535 case 2: 3536 do_something_else(); 3537 break; 3538 default: 3539 break; 3540 } 3541 if (condition) 3542 do_something_completely_different(); 3543 3544 if (x == y) { 3545 q(); 3546 } else if (x > y) { 3547 w(); 3548 } else { 3549 r(); 3550 } 3551 } 3552 3553A style similar to the default Visual Studio formatting style: 3554 3555.. code-block:: yaml 3556 3557 UseTab: Never 3558 IndentWidth: 4 3559 BreakBeforeBraces: Allman 3560 AllowShortIfStatementsOnASingleLine: false 3561 IndentCaseLabels: false 3562 ColumnLimit: 0 3563 3564The result is: 3565 3566.. code-block:: c++ 3567 3568 void test() 3569 { 3570 switch (suffix) 3571 { 3572 case 0: 3573 case 1: 3574 do_something(); 3575 break; 3576 case 2: 3577 do_something_else(); 3578 break; 3579 default: 3580 break; 3581 } 3582 if (condition) 3583 do_somthing_completely_different(); 3584 3585 if (x == y) 3586 { 3587 q(); 3588 } 3589 else if (x > y) 3590 { 3591 w(); 3592 } 3593 else 3594 { 3595 r(); 3596 } 3597 } 3598