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://www.chromium.org/developers/coding-style>`_ 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 155.. START_FORMAT_STYLE_OPTIONS 156 157**AccessModifierOffset** (``int``) 158 The extra indent or outdent of access modifiers, e.g. ``public:``. 159 160**AlignAfterOpenBracket** (``BracketAlignmentStyle``) 161 If ``true``, horizontally aligns arguments after an open bracket. 162 163 This applies to round brackets (parentheses), angle brackets and square 164 brackets. 165 166 Possible values: 167 168 * ``BAS_Align`` (in configuration: ``Align``) 169 Align parameters on the open bracket, e.g.: 170 171 .. code-block:: c++ 172 173 someLongFunction(argument1, 174 argument2); 175 176 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 177 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 178 179 .. code-block:: c++ 180 181 someLongFunction(argument1, 182 argument2); 183 184 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 185 Always break after an open bracket, if the parameters don't fit 186 on a single line, e.g.: 187 188 .. code-block:: c++ 189 190 someLongFunction( 191 argument1, argument2); 192 193 194 195**AlignConsecutiveAssignments** (``bool``) 196 If ``true``, aligns consecutive assignments. 197 198 This will align the assignment operators of consecutive lines. This 199 will result in formattings like 200 201 .. code-block:: c++ 202 203 int aaaa = 12; 204 int b = 23; 205 int ccc = 23; 206 207**AlignConsecutiveDeclarations** (``bool``) 208 If ``true``, aligns consecutive declarations. 209 210 This will align the declaration names of consecutive lines. This 211 will result in formattings like 212 213 .. code-block:: c++ 214 215 int aaaa = 12; 216 float b = 23; 217 std::string ccc = 23; 218 219**AlignConsecutiveMacros** (``bool``) 220 If ``true``, aligns consecutive C/C++ preprocessor macros. 221 222 This will align C/C++ preprocessor macros of consecutive lines. 223 Will result in formattings like 224 225 .. code-block:: c++ 226 227 #define SHORT_NAME 42 228 #define LONGER_NAME 0x007f 229 #define EVEN_LONGER_NAME (2) 230 #define foo(x) (x * x) 231 #define bar(y, z) (y + z) 232 233**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) 234 Options for aligning backslashes in escaped newlines. 235 236 Possible values: 237 238 * ``ENAS_DontAlign`` (in configuration: ``DontAlign``) 239 Don't align escaped newlines. 240 241 .. code-block:: c++ 242 243 #define A \ 244 int aaaa; \ 245 int b; \ 246 int dddddddddd; 247 248 * ``ENAS_Left`` (in configuration: ``Left``) 249 Align escaped newlines as far left as possible. 250 251 .. code-block:: c++ 252 253 true: 254 #define A \ 255 int aaaa; \ 256 int b; \ 257 int dddddddddd; 258 259 false: 260 261 * ``ENAS_Right`` (in configuration: ``Right``) 262 Align escaped newlines in the right-most column. 263 264 .. code-block:: c++ 265 266 #define A \ 267 int aaaa; \ 268 int b; \ 269 int dddddddddd; 270 271 272 273**AlignOperands** (``bool``) 274 If ``true``, horizontally align operands of binary and ternary 275 expressions. 276 277 Specifically, this aligns operands of a single expression that needs to be 278 split over multiple lines, e.g.: 279 280 .. code-block:: c++ 281 282 int aaa = bbbbbbbbbbbbbbb + 283 ccccccccccccccc; 284 285**AlignTrailingComments** (``bool``) 286 If ``true``, aligns trailing comments. 287 288 .. code-block:: c++ 289 290 true: false: 291 int a; // My comment a vs. int a; // My comment a 292 int b = 2; // comment b int b = 2; // comment about b 293 294**AllowAllArgumentsOnNextLine** (``bool``) 295 If a function call or braced initializer list doesn't fit on a 296 line, allow putting all arguments onto the next line, even if 297 ``BinPackArguments`` is ``false``. 298 299 .. code-block:: c++ 300 301 true: 302 callFunction( 303 a, b, c, d); 304 305 false: 306 callFunction(a, 307 b, 308 c, 309 d); 310 311**AllowAllConstructorInitializersOnNextLine** (``bool``) 312 If a constructor definition with a member initializer list doesn't 313 fit on a single line, allow putting all member initializers onto the next 314 line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true. 315 Note that this parameter has no effect if 316 ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false. 317 318 .. code-block:: c++ 319 320 true: 321 MyClass::MyClass() : 322 member0(0), member1(2) {} 323 324 false: 325 MyClass::MyClass() : 326 member0(0), 327 member1(2) {} 328 329**AllowAllParametersOfDeclarationOnNextLine** (``bool``) 330 If the function declaration doesn't fit on a line, 331 allow putting all parameters of a function declaration onto 332 the next line even if ``BinPackParameters`` is ``false``. 333 334 .. code-block:: c++ 335 336 true: 337 void myFunction( 338 int a, int b, int c, int d, int e); 339 340 false: 341 void myFunction(int a, 342 int b, 343 int c, 344 int d, 345 int e); 346 347**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) 348 Dependent on the value, ``while (true) { continue; }`` can be put on a 349 single line. 350 351 Possible values: 352 353 * ``SBS_Never`` (in configuration: ``Never``) 354 Never merge blocks into a single line. 355 356 .. code-block:: c++ 357 358 while (true) { 359 } 360 while (true) { 361 continue; 362 } 363 364 * ``SBS_Empty`` (in configuration: ``Empty``) 365 Only merge empty blocks. 366 367 .. code-block:: c++ 368 369 while (true) {} 370 while (true) { 371 continue; 372 } 373 374 * ``SBS_Always`` (in configuration: ``Always``) 375 Always merge short blocks into a single line. 376 377 .. code-block:: c++ 378 379 while (true) {} 380 while (true) { continue; } 381 382 383 384**AllowShortCaseLabelsOnASingleLine** (``bool``) 385 If ``true``, short case labels will be contracted to a single line. 386 387 .. code-block:: c++ 388 389 true: false: 390 switch (a) { vs. switch (a) { 391 case 1: x = 1; break; case 1: 392 case 2: return; x = 1; 393 } break; 394 case 2: 395 return; 396 } 397 398**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) 399 Dependent on the value, ``int f() { return 0; }`` can be put on a 400 single line. 401 402 Possible values: 403 404 * ``SFS_None`` (in configuration: ``None``) 405 Never merge functions into a single line. 406 407 * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) 408 Only merge functions defined inside a class. Same as "inline", 409 except it does not implies "empty": i.e. top level empty functions 410 are not merged either. 411 412 .. code-block:: c++ 413 414 class Foo { 415 void f() { foo(); } 416 }; 417 void f() { 418 foo(); 419 } 420 void f() { 421 } 422 423 * ``SFS_Empty`` (in configuration: ``Empty``) 424 Only merge empty functions. 425 426 .. code-block:: c++ 427 428 void f() {} 429 void f2() { 430 bar2(); 431 } 432 433 * ``SFS_Inline`` (in configuration: ``Inline``) 434 Only merge functions defined inside a class. Implies "empty". 435 436 .. code-block:: c++ 437 438 class Foo { 439 void f() { foo(); } 440 }; 441 void f() { 442 foo(); 443 } 444 void f() {} 445 446 * ``SFS_All`` (in configuration: ``All``) 447 Merge all functions fitting on a single line. 448 449 .. code-block:: c++ 450 451 class Foo { 452 void f() { foo(); } 453 }; 454 void f() { bar(); } 455 456 457 458**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) 459 If ``true``, ``if (a) return;`` can be put on a single line. 460 461 Possible values: 462 463 * ``SIS_Never`` (in configuration: ``Never``) 464 Never put short ifs on the same line. 465 466 .. code-block:: c++ 467 468 if (a) 469 return ; 470 else { 471 return; 472 } 473 474 * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``) 475 Without else put short ifs on the same line only if 476 the else is not a compound statement. 477 478 .. code-block:: c++ 479 480 if (a) return; 481 else 482 return; 483 484 * ``SIS_Always`` (in configuration: ``Always``) 485 Always put short ifs on the same line if 486 the else is not a compound statement or not. 487 488 .. code-block:: c++ 489 490 if (a) return; 491 else { 492 return; 493 } 494 495 496 497**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) 498 Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a 499 single line. 500 501 Possible values: 502 503 * ``SLS_None`` (in configuration: ``None``) 504 Never merge lambdas into a single line. 505 506 * ``SLS_Empty`` (in configuration: ``Empty``) 507 Only merge empty lambdas. 508 509 .. code-block:: c++ 510 511 auto lambda = [](int a) {} 512 auto lambda2 = [](int a) { 513 return a; 514 }; 515 516 * ``SLS_Inline`` (in configuration: ``Inline``) 517 Merge lambda into a single line if argument of a function. 518 519 .. code-block:: c++ 520 521 auto lambda = [](int a) { 522 return a; 523 }; 524 sort(a.begin(), a.end(), ()[] { return x < y; }) 525 526 * ``SLS_All`` (in configuration: ``All``) 527 Merge all lambdas fitting on a single line. 528 529 .. code-block:: c++ 530 531 auto lambda = [](int a) {} 532 auto lambda2 = [](int a) { return a; }; 533 534 535 536**AllowShortLoopsOnASingleLine** (``bool``) 537 If ``true``, ``while (true) continue;`` can be put on a single 538 line. 539 540**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) 541 The function definition return type breaking style to use. This 542 option is **deprecated** and is retained for backwards compatibility. 543 544 Possible values: 545 546 * ``DRTBS_None`` (in configuration: ``None``) 547 Break after return type automatically. 548 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 549 550 * ``DRTBS_All`` (in configuration: ``All``) 551 Always break after the return type. 552 553 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) 554 Always break after the return types of top-level functions. 555 556 557 558**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``) 559 The function declaration return type breaking style to use. 560 561 Possible values: 562 563 * ``RTBS_None`` (in configuration: ``None``) 564 Break after return type automatically. 565 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 566 567 .. code-block:: c++ 568 569 class A { 570 int f() { return 0; }; 571 }; 572 int f(); 573 int f() { return 1; } 574 575 * ``RTBS_All`` (in configuration: ``All``) 576 Always break after the return type. 577 578 .. code-block:: c++ 579 580 class A { 581 int 582 f() { 583 return 0; 584 }; 585 }; 586 int 587 f(); 588 int 589 f() { 590 return 1; 591 } 592 593 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) 594 Always break after the return types of top-level functions. 595 596 .. code-block:: c++ 597 598 class A { 599 int f() { return 0; }; 600 }; 601 int 602 f(); 603 int 604 f() { 605 return 1; 606 } 607 608 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) 609 Always break after the return type of function definitions. 610 611 .. code-block:: c++ 612 613 class A { 614 int 615 f() { 616 return 0; 617 }; 618 }; 619 int f(); 620 int 621 f() { 622 return 1; 623 } 624 625 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) 626 Always break after the return type of top-level definitions. 627 628 .. code-block:: c++ 629 630 class A { 631 int f() { return 0; }; 632 }; 633 int f(); 634 int 635 f() { 636 return 1; 637 } 638 639 640 641**AlwaysBreakBeforeMultilineStrings** (``bool``) 642 If ``true``, always break before multiline string literals. 643 644 This flag is mean to make cases where there are multiple multiline strings 645 in a file look more consistent. Thus, it will only take effect if wrapping 646 the string at that point leads to it being indented 647 ``ContinuationIndentWidth`` spaces from the start of the line. 648 649 .. code-block:: c++ 650 651 true: false: 652 aaaa = vs. aaaa = "bbbb" 653 "bbbb" "cccc"; 654 "cccc"; 655 656**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) 657 The template declaration breaking style to use. 658 659 Possible values: 660 661 * ``BTDS_No`` (in configuration: ``No``) 662 Do not force break before declaration. 663 ``PenaltyBreakTemplateDeclaration`` is taken into account. 664 665 .. code-block:: c++ 666 667 template <typename T> T foo() { 668 } 669 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, 670 int bbbbbbbbbbbbbbbbbbbbb) { 671 } 672 673 * ``BTDS_MultiLine`` (in configuration: ``MultiLine``) 674 Force break after template declaration only when the following 675 declaration spans multiple lines. 676 677 .. code-block:: c++ 678 679 template <typename T> T foo() { 680 } 681 template <typename T> 682 T foo(int aaaaaaaaaaaaaaaaaaaaa, 683 int bbbbbbbbbbbbbbbbbbbbb) { 684 } 685 686 * ``BTDS_Yes`` (in configuration: ``Yes``) 687 Always break after template declaration. 688 689 .. code-block:: c++ 690 691 template <typename T> 692 T foo() { 693 } 694 template <typename T> 695 T foo(int aaaaaaaaaaaaaaaaaaaaa, 696 int bbbbbbbbbbbbbbbbbbbbb) { 697 } 698 699 700 701**BinPackArguments** (``bool``) 702 If ``false``, a function call's arguments will either be all on the 703 same line or will have one line each. 704 705 .. code-block:: c++ 706 707 true: 708 void f() { 709 f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, 710 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 711 } 712 713 false: 714 void f() { 715 f(aaaaaaaaaaaaaaaaaaaa, 716 aaaaaaaaaaaaaaaaaaaa, 717 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 718 } 719 720**BinPackParameters** (``bool``) 721 If ``false``, a function declaration's or function definition's 722 parameters will either all be on the same line or will have one line each. 723 724 .. code-block:: c++ 725 726 true: 727 void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa, 728 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 729 730 false: 731 void f(int aaaaaaaaaaaaaaaaaaaa, 732 int aaaaaaaaaaaaaaaaaaaa, 733 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 734 735**BraceWrapping** (``BraceWrappingFlags``) 736 Control of individual brace wrapping cases. 737 738 If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how 739 each individual brace case should be handled. Otherwise, this is ignored. 740 741 .. code-block:: yaml 742 743 # Example of usage: 744 BreakBeforeBraces: Custom 745 BraceWrapping: 746 AfterEnum: true 747 AfterStruct: false 748 SplitEmptyFunction: false 749 750 Nested configuration flags: 751 752 753 * ``bool AfterCaseLabel`` Wrap case labels. 754 755 .. code-block:: c++ 756 757 false: true: 758 switch (foo) { vs. switch (foo) { 759 case 1: { case 1: 760 bar(); { 761 break; bar(); 762 } break; 763 default: { } 764 plop(); default: 765 } { 766 } plop(); 767 } 768 } 769 770 * ``bool AfterClass`` Wrap class definitions. 771 772 .. code-block:: c++ 773 774 true: 775 class foo {}; 776 777 false: 778 class foo 779 {}; 780 781 * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..). 782 783 .. code-block:: c++ 784 785 true: 786 if (foo()) 787 { 788 } else 789 {} 790 for (int i = 0; i < 10; ++i) 791 {} 792 793 false: 794 if (foo()) { 795 } else { 796 } 797 for (int i = 0; i < 10; ++i) { 798 } 799 800 * ``bool AfterEnum`` Wrap enum definitions. 801 802 .. code-block:: c++ 803 804 true: 805 enum X : int 806 { 807 B 808 }; 809 810 false: 811 enum X : int { B }; 812 813 * ``bool AfterFunction`` Wrap function definitions. 814 815 .. code-block:: c++ 816 817 true: 818 void foo() 819 { 820 bar(); 821 bar2(); 822 } 823 824 false: 825 void foo() { 826 bar(); 827 bar2(); 828 } 829 830 * ``bool AfterNamespace`` Wrap namespace definitions. 831 832 .. code-block:: c++ 833 834 true: 835 namespace 836 { 837 int foo(); 838 int bar(); 839 } 840 841 false: 842 namespace { 843 int foo(); 844 int bar(); 845 } 846 847 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). 848 @autoreleasepool and @synchronized blocks are wrapped 849 according to `AfterControlStatement` flag. 850 851 * ``bool AfterStruct`` Wrap struct definitions. 852 853 .. code-block:: c++ 854 855 true: 856 struct foo 857 { 858 int x; 859 }; 860 861 false: 862 struct foo { 863 int x; 864 }; 865 866 * ``bool AfterUnion`` Wrap union definitions. 867 868 .. code-block:: c++ 869 870 true: 871 union foo 872 { 873 int x; 874 } 875 876 false: 877 union foo { 878 int x; 879 } 880 881 * ``bool AfterExternBlock`` Wrap extern blocks. 882 883 .. code-block:: c++ 884 885 true: 886 extern "C" 887 { 888 int foo(); 889 } 890 891 false: 892 extern "C" { 893 int foo(); 894 } 895 896 * ``bool BeforeCatch`` Wrap before ``catch``. 897 898 .. code-block:: c++ 899 900 true: 901 try { 902 foo(); 903 } 904 catch () { 905 } 906 907 false: 908 try { 909 foo(); 910 } catch () { 911 } 912 913 * ``bool BeforeElse`` Wrap before ``else``. 914 915 .. code-block:: c++ 916 917 true: 918 if (foo()) { 919 } 920 else { 921 } 922 923 false: 924 if (foo()) { 925 } else { 926 } 927 928 * ``bool IndentBraces`` Indent the wrapped braces themselves. 929 930 * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line. 931 This option is used only if the opening brace of the function has 932 already been wrapped, i.e. the `AfterFunction` brace wrapping mode is 933 set, and the function could/should not be put on a single line (as per 934 `AllowShortFunctionsOnASingleLine` and constructor formatting options). 935 936 .. code-block:: c++ 937 938 int f() vs. inf f() 939 {} { 940 } 941 942 * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body 943 can be put on a single line. This option is used only if the opening 944 brace of the record has already been wrapped, i.e. the `AfterClass` 945 (for classes) brace wrapping mode is set. 946 947 .. code-block:: c++ 948 949 class Foo vs. class Foo 950 {} { 951 } 952 953 * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line. 954 This option is used only if the opening brace of the namespace has 955 already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is 956 set. 957 958 .. code-block:: c++ 959 960 namespace Foo vs. namespace Foo 961 {} { 962 } 963 964 965**BreakAfterJavaFieldAnnotations** (``bool``) 966 Break after each annotation on a field in Java files. 967 968 .. code-block:: java 969 970 true: false: 971 @Partial vs. @Partial @Mock DataLoad loader; 972 @Mock 973 DataLoad loader; 974 975**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) 976 The way to wrap binary operators. 977 978 Possible values: 979 980 * ``BOS_None`` (in configuration: ``None``) 981 Break after operators. 982 983 .. code-block:: c++ 984 985 LooooooooooongType loooooooooooooooooooooongVariable = 986 someLooooooooooooooooongFunction(); 987 988 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + 989 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == 990 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && 991 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > 992 ccccccccccccccccccccccccccccccccccccccccc; 993 994 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) 995 Break before operators that aren't assignments. 996 997 .. code-block:: c++ 998 999 LooooooooooongType loooooooooooooooooooooongVariable = 1000 someLooooooooooooooooongFunction(); 1001 1002 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1003 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1004 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1005 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1006 > ccccccccccccccccccccccccccccccccccccccccc; 1007 1008 * ``BOS_All`` (in configuration: ``All``) 1009 Break before operators. 1010 1011 .. code-block:: c++ 1012 1013 LooooooooooongType loooooooooooooooooooooongVariable 1014 = someLooooooooooooooooongFunction(); 1015 1016 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1017 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1018 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1019 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1020 > ccccccccccccccccccccccccccccccccccccccccc; 1021 1022 1023 1024**BreakBeforeBraces** (``BraceBreakingStyle``) 1025 The brace breaking style to use. 1026 1027 Possible values: 1028 1029 * ``BS_Attach`` (in configuration: ``Attach``) 1030 Always attach braces to surrounding context. 1031 1032 .. code-block:: c++ 1033 1034 try { 1035 foo(); 1036 } catch () { 1037 } 1038 void foo() { bar(); } 1039 class foo {}; 1040 if (foo()) { 1041 } else { 1042 } 1043 enum X : int { A, B }; 1044 1045 * ``BS_Linux`` (in configuration: ``Linux``) 1046 Like ``Attach``, but break before braces on function, namespace and 1047 class definitions. 1048 1049 .. code-block:: c++ 1050 1051 try { 1052 foo(); 1053 } catch () { 1054 } 1055 void foo() { bar(); } 1056 class foo 1057 { 1058 }; 1059 if (foo()) { 1060 } else { 1061 } 1062 enum X : int { A, B }; 1063 1064 * ``BS_Mozilla`` (in configuration: ``Mozilla``) 1065 Like ``Attach``, but break before braces on enum, function, and record 1066 definitions. 1067 1068 .. code-block:: c++ 1069 1070 try { 1071 foo(); 1072 } catch () { 1073 } 1074 void foo() { bar(); } 1075 class foo 1076 { 1077 }; 1078 if (foo()) { 1079 } else { 1080 } 1081 enum X : int { A, B }; 1082 1083 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) 1084 Like ``Attach``, but break before function definitions, ``catch``, and 1085 ``else``. 1086 1087 .. code-block:: c++ 1088 1089 try { 1090 foo(); 1091 } 1092 catch () { 1093 } 1094 void foo() { bar(); } 1095 class foo { 1096 }; 1097 if (foo()) { 1098 } 1099 else { 1100 } 1101 enum X : int { A, B }; 1102 1103 * ``BS_Allman`` (in configuration: ``Allman``) 1104 Always break before braces. 1105 1106 .. code-block:: c++ 1107 1108 try 1109 { 1110 foo(); 1111 } 1112 catch () 1113 { 1114 } 1115 void foo() { bar(); } 1116 class foo 1117 { 1118 }; 1119 if (foo()) 1120 { 1121 } 1122 else 1123 { 1124 } 1125 enum X : int 1126 { 1127 A, 1128 B 1129 }; 1130 1131 * ``BS_GNU`` (in configuration: ``GNU``) 1132 Always break before braces and add an extra level of indentation to 1133 braces of control statements, not to those of class, function 1134 or other definitions. 1135 1136 .. code-block:: c++ 1137 1138 try 1139 { 1140 foo(); 1141 } 1142 catch () 1143 { 1144 } 1145 void foo() { bar(); } 1146 class foo 1147 { 1148 }; 1149 if (foo()) 1150 { 1151 } 1152 else 1153 { 1154 } 1155 enum X : int 1156 { 1157 A, 1158 B 1159 }; 1160 1161 * ``BS_WebKit`` (in configuration: ``WebKit``) 1162 Like ``Attach``, but break before functions. 1163 1164 .. code-block:: c++ 1165 1166 try { 1167 foo(); 1168 } catch () { 1169 } 1170 void foo() { bar(); } 1171 class foo { 1172 }; 1173 if (foo()) { 1174 } else { 1175 } 1176 enum X : int { A, B }; 1177 1178 * ``BS_Custom`` (in configuration: ``Custom``) 1179 Configure each individual brace in `BraceWrapping`. 1180 1181 1182 1183**BreakBeforeTernaryOperators** (``bool``) 1184 If ``true``, ternary operators will be placed after line breaks. 1185 1186 .. code-block:: c++ 1187 1188 true: 1189 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription 1190 ? firstValue 1191 : SecondValueVeryVeryVeryVeryLong; 1192 1193 false: 1194 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? 1195 firstValue : 1196 SecondValueVeryVeryVeryVeryLong; 1197 1198**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) 1199 The constructor initializers style to use. 1200 1201 Possible values: 1202 1203 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) 1204 Break constructor initializers before the colon and after the commas. 1205 1206 .. code-block:: c++ 1207 1208 Constructor() 1209 : initializer1(), 1210 initializer2() 1211 1212 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) 1213 Break constructor initializers before the colon and commas, and align 1214 the commas with the colon. 1215 1216 .. code-block:: c++ 1217 1218 Constructor() 1219 : initializer1() 1220 , initializer2() 1221 1222 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) 1223 Break constructor initializers after the colon and commas. 1224 1225 .. code-block:: c++ 1226 1227 Constructor() : 1228 initializer1(), 1229 initializer2() 1230 1231 1232 1233**BreakInheritanceList** (``BreakInheritanceListStyle``) 1234 The inheritance list style to use. 1235 1236 Possible values: 1237 1238 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) 1239 Break inheritance list before the colon and after the commas. 1240 1241 .. code-block:: c++ 1242 1243 class Foo 1244 : Base1, 1245 Base2 1246 {}; 1247 1248 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) 1249 Break inheritance list before the colon and commas, and align 1250 the commas with the colon. 1251 1252 .. code-block:: c++ 1253 1254 class Foo 1255 : Base1 1256 , Base2 1257 {}; 1258 1259 * ``BILS_AfterColon`` (in configuration: ``AfterColon``) 1260 Break inheritance list after the colon and commas. 1261 1262 .. code-block:: c++ 1263 1264 class Foo : 1265 Base1, 1266 Base2 1267 {}; 1268 1269 1270 1271**BreakStringLiterals** (``bool``) 1272 Allow breaking string literals when formatting. 1273 1274**ColumnLimit** (``unsigned``) 1275 The column limit. 1276 1277 A column limit of ``0`` means that there is no column limit. In this case, 1278 clang-format will respect the input's line breaking decisions within 1279 statements unless they contradict other rules. 1280 1281**CommentPragmas** (``std::string``) 1282 A regular expression that describes comments with special meaning, 1283 which should not be split into lines or otherwise changed. 1284 1285 .. code-block:: c++ 1286 1287 // CommentPragmas: '^ FOOBAR pragma:' 1288 // Will leave the following line unaffected 1289 #include <vector> // FOOBAR pragma: keep 1290 1291**CompactNamespaces** (``bool``) 1292 If ``true``, consecutive namespace declarations will be on the same 1293 line. If ``false``, each namespace is declared on a new line. 1294 1295 .. code-block:: c++ 1296 1297 true: 1298 namespace Foo { namespace Bar { 1299 }} 1300 1301 false: 1302 namespace Foo { 1303 namespace Bar { 1304 } 1305 } 1306 1307 If it does not fit on a single line, the overflowing namespaces get 1308 wrapped: 1309 1310 .. code-block:: c++ 1311 1312 namespace Foo { namespace Bar { 1313 namespace Extra { 1314 }}} 1315 1316**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) 1317 If the constructor initializers don't fit on a line, put each 1318 initializer on its own line. 1319 1320 .. code-block:: c++ 1321 1322 true: 1323 SomeClass::Constructor() 1324 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 1325 return 0; 1326 } 1327 1328 false: 1329 SomeClass::Constructor() 1330 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), 1331 aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 1332 return 0; 1333 } 1334 1335**ConstructorInitializerIndentWidth** (``unsigned``) 1336 The number of characters to use for indentation of constructor 1337 initializer lists as well as inheritance lists. 1338 1339**ContinuationIndentWidth** (``unsigned``) 1340 Indent width for line continuations. 1341 1342 .. code-block:: c++ 1343 1344 ContinuationIndentWidth: 2 1345 1346 int i = // VeryVeryVeryVeryVeryLongComment 1347 longFunction( // Again a long comment 1348 arg); 1349 1350**Cpp11BracedListStyle** (``bool``) 1351 If ``true``, format braced lists as best suited for C++11 braced 1352 lists. 1353 1354 Important differences: 1355 - No spaces inside the braced list. 1356 - No line break before the closing brace. 1357 - Indentation with the continuation indent, not with the block indent. 1358 1359 Fundamentally, C++11 braced lists are formatted exactly like function 1360 calls would be formatted in their place. If the braced list follows a name 1361 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 1362 the parentheses of a function call with that name. If there is no name, 1363 a zero-length name is assumed. 1364 1365 .. code-block:: c++ 1366 1367 true: false: 1368 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 }; 1369 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} }; 1370 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); 1371 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; 1372 1373**DerivePointerAlignment** (``bool``) 1374 If ``true``, analyze the formatted file for the most common 1375 alignment of ``&`` and ``*``. 1376 Pointer and reference alignment styles are going to be updated according 1377 to the preferences found in the file. 1378 ``PointerAlignment`` is then used only as fallback. 1379 1380**DisableFormat** (``bool``) 1381 Disables formatting completely. 1382 1383**ExperimentalAutoDetectBinPacking** (``bool``) 1384 If ``true``, clang-format detects whether function calls and 1385 definitions are formatted with one parameter per line. 1386 1387 Each call can be bin-packed, one-per-line or inconclusive. If it is 1388 inconclusive, e.g. completely on one line, but a decision needs to be 1389 made, clang-format analyzes whether there are other bin-packed cases in 1390 the input file and act accordingly. 1391 1392 NOTE: This is an experimental flag, that might go away or be renamed. Do 1393 not use this in config files, etc. Use at your own risk. 1394 1395**FixNamespaceComments** (``bool``) 1396 If ``true``, clang-format adds missing namespace end comments and 1397 fixes invalid existing ones. 1398 1399 .. code-block:: c++ 1400 1401 true: false: 1402 namespace a { vs. namespace a { 1403 foo(); foo(); 1404 } // namespace a } 1405 1406**ForEachMacros** (``std::vector<std::string>``) 1407 A vector of macros that should be interpreted as foreach loops 1408 instead of as function calls. 1409 1410 These are expected to be macros of the form: 1411 1412 .. code-block:: c++ 1413 1414 FOREACH(<variable-declaration>, ...) 1415 <loop-body> 1416 1417 In the .clang-format configuration file, this can be configured like: 1418 1419 .. code-block:: yaml 1420 1421 ForEachMacros: ['RANGES_FOR', 'FOREACH'] 1422 1423 For example: BOOST_FOREACH. 1424 1425**IncludeBlocks** (``IncludeBlocksStyle``) 1426 Dependent on the value, multiple ``#include`` blocks can be sorted 1427 as one and divided based on category. 1428 1429 Possible values: 1430 1431 * ``IBS_Preserve`` (in configuration: ``Preserve``) 1432 Sort each ``#include`` block separately. 1433 1434 .. code-block:: c++ 1435 1436 #include "b.h" into #include "b.h" 1437 1438 #include <lib/main.h> #include "a.h" 1439 #include "a.h" #include <lib/main.h> 1440 1441 * ``IBS_Merge`` (in configuration: ``Merge``) 1442 Merge multiple ``#include`` blocks together and sort as one. 1443 1444 .. code-block:: c++ 1445 1446 #include "b.h" into #include "a.h" 1447 #include "b.h" 1448 #include <lib/main.h> #include <lib/main.h> 1449 #include "a.h" 1450 1451 * ``IBS_Regroup`` (in configuration: ``Regroup``) 1452 Merge multiple ``#include`` blocks together and sort as one. 1453 Then split into groups based on category priority. See 1454 ``IncludeCategories``. 1455 1456 .. code-block:: c++ 1457 1458 #include "b.h" into #include "a.h" 1459 #include "b.h" 1460 #include <lib/main.h> 1461 #include "a.h" #include <lib/main.h> 1462 1463 1464 1465**IncludeCategories** (``std::vector<IncludeCategory>``) 1466 Regular expressions denoting the different ``#include`` categories 1467 used for ordering ``#includes``. 1468 1469 `POSIX extended 1470 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ 1471 regular expressions are supported. 1472 1473 These regular expressions are matched against the filename of an include 1474 (including the <> or "") in order. The value belonging to the first 1475 matching regular expression is assigned and ``#includes`` are sorted first 1476 according to increasing category number and then alphabetically within 1477 each category. 1478 1479 If none of the regular expressions match, INT_MAX is assigned as 1480 category. The main header for a source file automatically gets category 0. 1481 so that it is generally kept at the beginning of the ``#includes`` 1482 (https://llvm.org/docs/CodingStandards.html#include-style). However, you 1483 can also assign negative priorities if you have certain headers that 1484 always need to be first. 1485 1486 To configure this in the .clang-format file, use: 1487 1488 .. code-block:: yaml 1489 1490 IncludeCategories: 1491 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 1492 Priority: 2 1493 - Regex: '^(<|"(gtest|gmock|isl|json)/)' 1494 Priority: 3 1495 - Regex: '<[[:alnum:].]+>' 1496 Priority: 4 1497 - Regex: '.*' 1498 Priority: 1 1499 1500**IncludeIsMainRegex** (``std::string``) 1501 Specify a regular expression of suffixes that are allowed in the 1502 file-to-main-include mapping. 1503 1504 When guessing whether a #include is the "main" include (to assign 1505 category 0, see above), use this regex of allowed suffixes to the header 1506 stem. A partial match is done, so that: 1507 - "" means "arbitrary suffix" 1508 - "$" means "no suffix" 1509 1510 For example, if configured to "(_test)?$", then a header a.h would be seen 1511 as the "main" include in both a.cc and a_test.cc. 1512 1513**IndentCaseLabels** (``bool``) 1514 Indent case labels one level from the switch statement. 1515 1516 When ``false``, use the same indentation level as for the switch statement. 1517 Switch statement body is always indented one level more than case labels. 1518 1519 .. code-block:: c++ 1520 1521 false: true: 1522 switch (fool) { vs. switch (fool) { 1523 case 1: case 1: 1524 bar(); bar(); 1525 break; break; 1526 default: default: 1527 plop(); plop(); 1528 } } 1529 1530**IndentGotoLabels** (``bool``) 1531 Indent goto labels. 1532 1533 When ``false``, goto labels are flushed left. 1534 1535 .. code-block:: c++ 1536 1537 true: false: 1538 int f() { vs. int f() { 1539 if (foo()) { if (foo()) { 1540 label1: label1: 1541 bar(); bar(); 1542 } } 1543 label2: label2: 1544 return 1; return 1; 1545 } } 1546 1547**IndentPPDirectives** (``PPDirectiveIndentStyle``) 1548 The preprocessor directive indenting style to use. 1549 1550 Possible values: 1551 1552 * ``PPDIS_None`` (in configuration: ``None``) 1553 Does not indent any directives. 1554 1555 .. code-block:: c++ 1556 1557 #if FOO 1558 #if BAR 1559 #include <foo> 1560 #endif 1561 #endif 1562 1563 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``) 1564 Indents directives after the hash. 1565 1566 .. code-block:: c++ 1567 1568 #if FOO 1569 # if BAR 1570 # include <foo> 1571 # endif 1572 #endif 1573 1574 * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) 1575 Indents directives before the hash. 1576 1577 .. code-block:: c++ 1578 1579 #if FOO 1580 #if BAR 1581 #include <foo> 1582 #endif 1583 #endif 1584 1585 1586 1587**IndentWidth** (``unsigned``) 1588 The number of columns to use for indentation. 1589 1590 .. code-block:: c++ 1591 1592 IndentWidth: 3 1593 1594 void f() { 1595 someFunction(); 1596 if (true, false) { 1597 f(); 1598 } 1599 } 1600 1601**IndentWrappedFunctionNames** (``bool``) 1602 Indent if a function definition or declaration is wrapped after the 1603 type. 1604 1605 .. code-block:: c++ 1606 1607 true: 1608 LoooooooooooooooooooooooooooooooooooooooongReturnType 1609 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 1610 1611 false: 1612 LoooooooooooooooooooooooooooooooooooooooongReturnType 1613 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 1614 1615**JavaImportGroups** (``std::vector<std::string>``) 1616 A vector of prefixes ordered by the desired groups for Java imports. 1617 1618 Each group is separated by a newline. Static imports will also follow the 1619 same grouping convention above all non-static imports. One group's prefix 1620 can be a subset of another - the longest prefix is always matched. Within 1621 a group, the imports are ordered lexicographically. 1622 1623 In the .clang-format configuration file, this can be configured like 1624 in the following yaml example. This will result in imports being 1625 formatted as in the Java example below. 1626 1627 .. code-block:: yaml 1628 1629 JavaImportGroups: ['com.example', 'com', 'org'] 1630 1631 1632 .. code-block:: java 1633 1634 import static com.example.function1; 1635 1636 import static com.test.function2; 1637 1638 import static org.example.function3; 1639 1640 import com.example.ClassA; 1641 import com.example.Test; 1642 import com.example.a.ClassB; 1643 1644 import com.test.ClassC; 1645 1646 import org.example.ClassD; 1647 1648**JavaScriptQuotes** (``JavaScriptQuoteStyle``) 1649 The JavaScriptQuoteStyle to use for JavaScript strings. 1650 1651 Possible values: 1652 1653 * ``JSQS_Leave`` (in configuration: ``Leave``) 1654 Leave string quotes as they are. 1655 1656 .. code-block:: js 1657 1658 string1 = "foo"; 1659 string2 = 'bar'; 1660 1661 * ``JSQS_Single`` (in configuration: ``Single``) 1662 Always use single quotes. 1663 1664 .. code-block:: js 1665 1666 string1 = 'foo'; 1667 string2 = 'bar'; 1668 1669 * ``JSQS_Double`` (in configuration: ``Double``) 1670 Always use double quotes. 1671 1672 .. code-block:: js 1673 1674 string1 = "foo"; 1675 string2 = "bar"; 1676 1677 1678 1679**JavaScriptWrapImports** (``bool``) 1680 Whether to wrap JavaScript import/export statements. 1681 1682 .. code-block:: js 1683 1684 true: 1685 import { 1686 VeryLongImportsAreAnnoying, 1687 VeryLongImportsAreAnnoying, 1688 VeryLongImportsAreAnnoying, 1689 } from 'some/module.js' 1690 1691 false: 1692 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" 1693 1694**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) 1695 If true, the empty line at the start of blocks is kept. 1696 1697 .. code-block:: c++ 1698 1699 true: false: 1700 if (foo) { vs. if (foo) { 1701 bar(); 1702 bar(); } 1703 } 1704 1705**Language** (``LanguageKind``) 1706 Language, this format style is targeted at. 1707 1708 Possible values: 1709 1710 * ``LK_None`` (in configuration: ``None``) 1711 Do not use. 1712 1713 * ``LK_Cpp`` (in configuration: ``Cpp``) 1714 Should be used for C, C++. 1715 1716 * ``LK_CSharp`` (in configuration: ``CSharp``) 1717 Should be used for C#. 1718 1719 * ``LK_Java`` (in configuration: ``Java``) 1720 Should be used for Java. 1721 1722 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 1723 Should be used for JavaScript. 1724 1725 * ``LK_ObjC`` (in configuration: ``ObjC``) 1726 Should be used for Objective-C, Objective-C++. 1727 1728 * ``LK_Proto`` (in configuration: ``Proto``) 1729 Should be used for Protocol Buffers 1730 (https://developers.google.com/protocol-buffers/). 1731 1732 * ``LK_TableGen`` (in configuration: ``TableGen``) 1733 Should be used for TableGen code. 1734 1735 * ``LK_TextProto`` (in configuration: ``TextProto``) 1736 Should be used for Protocol Buffer messages in text format 1737 (https://developers.google.com/protocol-buffers/). 1738 1739 1740 1741**MacroBlockBegin** (``std::string``) 1742 A regular expression matching macros that start a block. 1743 1744 .. code-block:: c++ 1745 1746 # With: 1747 MacroBlockBegin: "^NS_MAP_BEGIN|\ 1748 NS_TABLE_HEAD$" 1749 MacroBlockEnd: "^\ 1750 NS_MAP_END|\ 1751 NS_TABLE_.*_END$" 1752 1753 NS_MAP_BEGIN 1754 foo(); 1755 NS_MAP_END 1756 1757 NS_TABLE_HEAD 1758 bar(); 1759 NS_TABLE_FOO_END 1760 1761 # Without: 1762 NS_MAP_BEGIN 1763 foo(); 1764 NS_MAP_END 1765 1766 NS_TABLE_HEAD 1767 bar(); 1768 NS_TABLE_FOO_END 1769 1770**MacroBlockEnd** (``std::string``) 1771 A regular expression matching macros that end a block. 1772 1773**MaxEmptyLinesToKeep** (``unsigned``) 1774 The maximum number of consecutive empty lines to keep. 1775 1776 .. code-block:: c++ 1777 1778 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 1779 int f() { int f() { 1780 int = 1; int i = 1; 1781 i = foo(); 1782 i = foo(); return i; 1783 } 1784 return i; 1785 } 1786 1787**NamespaceIndentation** (``NamespaceIndentationKind``) 1788 The indentation used for namespaces. 1789 1790 Possible values: 1791 1792 * ``NI_None`` (in configuration: ``None``) 1793 Don't indent in namespaces. 1794 1795 .. code-block:: c++ 1796 1797 namespace out { 1798 int i; 1799 namespace in { 1800 int i; 1801 } 1802 } 1803 1804 * ``NI_Inner`` (in configuration: ``Inner``) 1805 Indent only in inner namespaces (nested in other namespaces). 1806 1807 .. code-block:: c++ 1808 1809 namespace out { 1810 int i; 1811 namespace in { 1812 int i; 1813 } 1814 } 1815 1816 * ``NI_All`` (in configuration: ``All``) 1817 Indent in all namespaces. 1818 1819 .. code-block:: c++ 1820 1821 namespace out { 1822 int i; 1823 namespace in { 1824 int i; 1825 } 1826 } 1827 1828 1829 1830**NamespaceMacros** (``std::vector<std::string>``) 1831 A vector of macros which are used to open namespace blocks. 1832 1833 These are expected to be macros of the form: 1834 1835 .. code-block:: c++ 1836 1837 NAMESPACE(<namespace-name>, ...) { 1838 <namespace-content> 1839 } 1840 1841 For example: TESTSUITE 1842 1843**ObjCBinPackProtocolList** (``BinPackStyle``) 1844 Controls bin-packing Objective-C protocol conformance list 1845 items into as few lines as possible when they go over ``ColumnLimit``. 1846 1847 If ``Auto`` (the default), delegates to the value in 1848 ``BinPackParameters``. If that is ``true``, bin-packs Objective-C 1849 protocol conformance list items into as few lines as possible 1850 whenever they go over ``ColumnLimit``. 1851 1852 If ``Always``, always bin-packs Objective-C protocol conformance 1853 list items into as few lines as possible whenever they go over 1854 ``ColumnLimit``. 1855 1856 If ``Never``, lays out Objective-C protocol conformance list items 1857 onto individual lines whenever they go over ``ColumnLimit``. 1858 1859 1860 .. code-block:: objc 1861 1862 Always (or Auto, if BinPackParameters=true): 1863 @interface ccccccccccccc () < 1864 ccccccccccccc, ccccccccccccc, 1865 ccccccccccccc, ccccccccccccc> { 1866 } 1867 1868 Never (or Auto, if BinPackParameters=false): 1869 @interface ddddddddddddd () < 1870 ddddddddddddd, 1871 ddddddddddddd, 1872 ddddddddddddd, 1873 ddddddddddddd> { 1874 } 1875 1876 Possible values: 1877 1878 * ``BPS_Auto`` (in configuration: ``Auto``) 1879 Automatically determine parameter bin-packing behavior. 1880 1881 * ``BPS_Always`` (in configuration: ``Always``) 1882 Always bin-pack parameters. 1883 1884 * ``BPS_Never`` (in configuration: ``Never``) 1885 Never bin-pack parameters. 1886 1887 1888 1889**ObjCBlockIndentWidth** (``unsigned``) 1890 The number of characters to use for indentation of ObjC blocks. 1891 1892 .. code-block:: objc 1893 1894 ObjCBlockIndentWidth: 4 1895 1896 [operation setCompletionBlock:^{ 1897 [self onOperationDone]; 1898 }]; 1899 1900**ObjCSpaceAfterProperty** (``bool``) 1901 Add a space after ``@property`` in Objective-C, i.e. use 1902 ``@property (readonly)`` instead of ``@property(readonly)``. 1903 1904**ObjCSpaceBeforeProtocolList** (``bool``) 1905 Add a space in front of an Objective-C protocol list, i.e. use 1906 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 1907 1908**PenaltyBreakAssignment** (``unsigned``) 1909 The penalty for breaking around an assignment operator. 1910 1911**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) 1912 The penalty for breaking a function call after ``call(``. 1913 1914**PenaltyBreakComment** (``unsigned``) 1915 The penalty for each line break introduced inside a comment. 1916 1917**PenaltyBreakFirstLessLess** (``unsigned``) 1918 The penalty for breaking before the first ``<<``. 1919 1920**PenaltyBreakString** (``unsigned``) 1921 The penalty for each line break introduced inside a string literal. 1922 1923**PenaltyBreakTemplateDeclaration** (``unsigned``) 1924 The penalty for breaking after template declaration. 1925 1926**PenaltyExcessCharacter** (``unsigned``) 1927 The penalty for each character outside of the column limit. 1928 1929**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) 1930 Penalty for putting the return type of a function onto its own 1931 line. 1932 1933**PointerAlignment** (``PointerAlignmentStyle``) 1934 Pointer and reference alignment style. 1935 1936 Possible values: 1937 1938 * ``PAS_Left`` (in configuration: ``Left``) 1939 Align pointer to the left. 1940 1941 .. code-block:: c++ 1942 1943 int* a; 1944 1945 * ``PAS_Right`` (in configuration: ``Right``) 1946 Align pointer to the right. 1947 1948 .. code-block:: c++ 1949 1950 int *a; 1951 1952 * ``PAS_Middle`` (in configuration: ``Middle``) 1953 Align pointer in the middle. 1954 1955 .. code-block:: c++ 1956 1957 int * a; 1958 1959 1960 1961**RawStringFormats** (``std::vector<RawStringFormat>``) 1962 Defines hints for detecting supported languages code blocks in raw 1963 strings. 1964 1965 A raw string with a matching delimiter or a matching enclosing function 1966 name will be reformatted assuming the specified language based on the 1967 style for that language defined in the .clang-format file. If no style has 1968 been defined in the .clang-format file for the specific language, a 1969 predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not 1970 found, the formatting is based on llvm style. A matching delimiter takes 1971 precedence over a matching enclosing function name for determining the 1972 language of the raw string contents. 1973 1974 If a canonical delimiter is specified, occurrences of other delimiters for 1975 the same language will be updated to the canonical if possible. 1976 1977 There should be at most one specification per language and each delimiter 1978 and enclosing function should not occur in multiple specifications. 1979 1980 To configure this in the .clang-format file, use: 1981 1982 .. code-block:: yaml 1983 1984 RawStringFormats: 1985 - Language: TextProto 1986 Delimiters: 1987 - 'pb' 1988 - 'proto' 1989 EnclosingFunctions: 1990 - 'PARSE_TEXT_PROTO' 1991 BasedOnStyle: google 1992 - Language: Cpp 1993 Delimiters: 1994 - 'cc' 1995 - 'cpp' 1996 BasedOnStyle: llvm 1997 CanonicalDelimiter: 'cc' 1998 1999**ReflowComments** (``bool``) 2000 If ``true``, clang-format will attempt to re-flow comments. 2001 2002 .. code-block:: c++ 2003 2004 false: 2005 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 2006 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 2007 2008 true: 2009 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 2010 // information 2011 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 2012 * information */ 2013 2014**SortIncludes** (``bool``) 2015 If ``true``, clang-format will sort ``#includes``. 2016 2017 .. code-block:: c++ 2018 2019 false: true: 2020 #include "b.h" vs. #include "a.h" 2021 #include "a.h" #include "b.h" 2022 2023**SortUsingDeclarations** (``bool``) 2024 If ``true``, clang-format will sort using declarations. 2025 2026 The order of using declarations is defined as follows: 2027 Split the strings by "::" and discard any initial empty strings. The last 2028 element of each list is a non-namespace name; all others are namespace 2029 names. Sort the lists of names lexicographically, where the sort order of 2030 individual names is that all non-namespace names come before all namespace 2031 names, and within those groups, names are in case-insensitive 2032 lexicographic order. 2033 2034 .. code-block:: c++ 2035 2036 false: true: 2037 using std::cout; vs. using std::cin; 2038 using std::cin; using std::cout; 2039 2040**SpaceAfterCStyleCast** (``bool``) 2041 If ``true``, a space is inserted after C style casts. 2042 2043 .. code-block:: c++ 2044 2045 true: false: 2046 (int) i; vs. (int)i; 2047 2048**SpaceAfterLogicalNot** (``bool``) 2049 If ``true``, a space is inserted after the logical not operator (``!``). 2050 2051 .. code-block:: c++ 2052 2053 true: false: 2054 ! someExpression(); vs. !someExpression(); 2055 2056**SpaceAfterTemplateKeyword** (``bool``) 2057 If ``true``, a space will be inserted after the 'template' keyword. 2058 2059 .. code-block:: c++ 2060 2061 true: false: 2062 template <int> void foo(); vs. template<int> void foo(); 2063 2064**SpaceBeforeAssignmentOperators** (``bool``) 2065 If ``false``, spaces will be removed before assignment operators. 2066 2067 .. code-block:: c++ 2068 2069 true: false: 2070 int a = 5; vs. int a= 5; 2071 a += 42; a+= 42; 2072 2073**SpaceBeforeCpp11BracedList** (``bool``) 2074 If ``true``, a space will be inserted before a C++11 braced list 2075 used to initialize an object (after the preceding identifier or type). 2076 2077 .. code-block:: c++ 2078 2079 true: false: 2080 Foo foo { bar }; vs. Foo foo{ bar }; 2081 Foo {}; Foo{}; 2082 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; 2083 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; 2084 2085**SpaceBeforeCtorInitializerColon** (``bool``) 2086 If ``false``, spaces will be removed before constructor initializer 2087 colon. 2088 2089 .. code-block:: c++ 2090 2091 true: false: 2092 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} 2093 2094**SpaceBeforeInheritanceColon** (``bool``) 2095 If ``false``, spaces will be removed before inheritance colon. 2096 2097 .. code-block:: c++ 2098 2099 true: false: 2100 class Foo : Bar {} vs. class Foo: Bar {} 2101 2102**SpaceBeforeParens** (``SpaceBeforeParensOptions``) 2103 Defines in which cases to put a space before opening parentheses. 2104 2105 Possible values: 2106 2107 * ``SBPO_Never`` (in configuration: ``Never``) 2108 Never put a space before opening parentheses. 2109 2110 .. code-block:: c++ 2111 2112 void f() { 2113 if(true) { 2114 f(); 2115 } 2116 } 2117 2118 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 2119 Put a space before opening parentheses only after control statement 2120 keywords (``for/if/while...``). 2121 2122 .. code-block:: c++ 2123 2124 void f() { 2125 if (true) { 2126 f(); 2127 } 2128 } 2129 2130 * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``) 2131 Put a space before opening parentheses only if the parentheses are not 2132 empty i.e. '()' 2133 2134 .. code-block:: c++ 2135 2136 void() { 2137 if (true) { 2138 f(); 2139 g (x, y, z); 2140 } 2141 } 2142 2143 * ``SBPO_Always`` (in configuration: ``Always``) 2144 Always put a space before opening parentheses, except when it's 2145 prohibited by the syntax rules (in function-like macro definitions) or 2146 when determined by other style rules (after unary operators, opening 2147 parentheses, etc.) 2148 2149 .. code-block:: c++ 2150 2151 void f () { 2152 if (true) { 2153 f (); 2154 } 2155 } 2156 2157 2158 2159**SpaceBeforeRangeBasedForLoopColon** (``bool``) 2160 If ``false``, spaces will be removed before range-based for loop 2161 colon. 2162 2163 .. code-block:: c++ 2164 2165 true: false: 2166 for (auto v : values) {} vs. for(auto v: values) {} 2167 2168**SpaceInEmptyBlock** (``bool``) 2169 If ``true``, spaces will be inserted into ``{}``. 2170 2171 .. code-block:: c++ 2172 2173 true: false: 2174 void f() { } vs. void f() {} 2175 while (true) { } while (true) {} 2176 2177**SpaceInEmptyParentheses** (``bool``) 2178 If ``true``, spaces may be inserted into ``()``. 2179 2180 .. code-block:: c++ 2181 2182 true: false: 2183 void f( ) { vs. void f() { 2184 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; 2185 if (true) { if (true) { 2186 f( ); f(); 2187 } } 2188 } } 2189 2190**SpacesBeforeTrailingComments** (``unsigned``) 2191 The number of spaces before trailing line comments 2192 (``//`` - comments). 2193 2194 This does not affect trailing block comments (``/*`` - comments) as 2195 those commonly have different usage patterns and a number of special 2196 cases. 2197 2198 .. code-block:: c++ 2199 2200 SpacesBeforeTrailingComments: 3 2201 void f() { 2202 if (true) { // foo1 2203 f(); // bar 2204 } // foo 2205 } 2206 2207**SpacesInAngles** (``bool``) 2208 If ``true``, spaces will be inserted after ``<`` and before ``>`` 2209 in template argument lists. 2210 2211 .. code-block:: c++ 2212 2213 true: false: 2214 static_cast< int >(arg); vs. static_cast<int>(arg); 2215 std::function< void(int) > fct; std::function<void(int)> fct; 2216 2217**SpacesInCStyleCastParentheses** (``bool``) 2218 If ``true``, spaces may be inserted into C style casts. 2219 2220 .. code-block:: c++ 2221 2222 true: false: 2223 x = ( int32 )y vs. x = (int32)y 2224 2225**SpacesInContainerLiterals** (``bool``) 2226 If ``true``, spaces are inserted inside container literals (e.g. 2227 ObjC and Javascript array and dict literals). 2228 2229 .. code-block:: js 2230 2231 true: false: 2232 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; 2233 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); 2234 2235**SpacesInParentheses** (``bool``) 2236 If ``true``, spaces will be inserted after ``(`` and before ``)``. 2237 2238 .. code-block:: c++ 2239 2240 true: false: 2241 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; 2242 2243**SpacesInSquareBrackets** (``bool``) 2244 If ``true``, spaces will be inserted after ``[`` and before ``]``. 2245 Lambdas or unspecified size array declarations will not be affected. 2246 2247 .. code-block:: c++ 2248 2249 true: false: 2250 int a[ 5 ]; vs. int a[5]; 2251 std::unique_ptr<int[]> foo() {} // Won't be affected 2252 2253**Standard** (``LanguageStandard``) 2254 Format compatible with this standard, e.g. use ``A<A<int> >`` 2255 instead of ``A<A<int>>`` for ``LS_Cpp03``. 2256 2257 Possible values: 2258 2259 * ``LS_Cpp03`` (in configuration: ``Cpp03``) 2260 Use C++03-compatible syntax. 2261 2262 * ``LS_Cpp11`` (in configuration: ``Cpp11``) 2263 Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of 2264 ``A<A<int> >``). 2265 2266 * ``LS_Auto`` (in configuration: ``Auto``) 2267 Automatic detection based on the input. 2268 2269 2270 2271**StatementMacros** (``std::vector<std::string>``) 2272 A vector of macros that should be interpreted as complete 2273 statements. 2274 2275 Typical macros are expressions, and require a semi-colon to be 2276 added; sometimes this is not the case, and this allows to make 2277 clang-format aware of such cases. 2278 2279 For example: Q_UNUSED 2280 2281**TabWidth** (``unsigned``) 2282 The number of columns used for tab stops. 2283 2284**TypenameMacros** (``std::vector<std::string>``) 2285 A vector of macros that should be interpreted as type declarations 2286 instead of as function calls. 2287 2288 These are expected to be macros of the form: 2289 2290 .. code-block:: c++ 2291 2292 STACK_OF(...) 2293 2294 In the .clang-format configuration file, this can be configured like: 2295 2296 .. code-block:: yaml 2297 2298 TypenameMacros: ['STACK_OF', 'LIST'] 2299 2300 For example: OpenSSL STACK_OF, BSD LIST_ENTRY. 2301 2302**UseTab** (``UseTabStyle``) 2303 The way to use tab characters in the resulting file. 2304 2305 Possible values: 2306 2307 * ``UT_Never`` (in configuration: ``Never``) 2308 Never use tab. 2309 2310 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 2311 Use tabs only for indentation. 2312 2313 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``) 2314 Use tabs only for line continuation and indentation. 2315 2316 * ``UT_Always`` (in configuration: ``Always``) 2317 Use tabs whenever we need to fill whitespace that spans at least from 2318 one tab stop to the next one. 2319 2320 2321 2322.. END_FORMAT_STYLE_OPTIONS 2323 2324Adding additional style options 2325=============================== 2326 2327Each additional style option adds costs to the clang-format project. Some of 2328these costs affect the clang-format development itself, as we need to make 2329sure that any given combination of options work and that new features don't 2330break any of the existing options in any way. There are also costs for end users 2331as options become less discoverable and people have to think about and make a 2332decision on options they don't really care about. 2333 2334The goal of the clang-format project is more on the side of supporting a 2335limited set of styles really well as opposed to supporting every single style 2336used by a codebase somewhere in the wild. Of course, we do want to support all 2337major projects and thus have established the following bar for adding style 2338options. Each new style option must .. 2339 2340 * be used in a project of significant size (have dozens of contributors) 2341 * have a publicly accessible style guide 2342 * have a person willing to contribute and maintain patches 2343 2344Examples 2345======== 2346 2347A style similar to the `Linux Kernel style 2348<https://www.kernel.org/doc/Documentation/CodingStyle>`_: 2349 2350.. code-block:: yaml 2351 2352 BasedOnStyle: LLVM 2353 IndentWidth: 8 2354 UseTab: Always 2355 BreakBeforeBraces: Linux 2356 AllowShortIfStatementsOnASingleLine: false 2357 IndentCaseLabels: false 2358 2359The result is (imagine that tabs are used for indentation here): 2360 2361.. code-block:: c++ 2362 2363 void test() 2364 { 2365 switch (x) { 2366 case 0: 2367 case 1: 2368 do_something(); 2369 break; 2370 case 2: 2371 do_something_else(); 2372 break; 2373 default: 2374 break; 2375 } 2376 if (condition) 2377 do_something_completely_different(); 2378 2379 if (x == y) { 2380 q(); 2381 } else if (x > y) { 2382 w(); 2383 } else { 2384 r(); 2385 } 2386 } 2387 2388A style similar to the default Visual Studio formatting style: 2389 2390.. code-block:: yaml 2391 2392 UseTab: Never 2393 IndentWidth: 4 2394 BreakBeforeBraces: Allman 2395 AllowShortIfStatementsOnASingleLine: false 2396 IndentCaseLabels: false 2397 ColumnLimit: 0 2398 2399The result is: 2400 2401.. code-block:: c++ 2402 2403 void test() 2404 { 2405 switch (suffix) 2406 { 2407 case 0: 2408 case 1: 2409 do_something(); 2410 break; 2411 case 2: 2412 do_something_else(); 2413 break; 2414 default: 2415 break; 2416 } 2417 if (condition) 2418 do_somthing_completely_different(); 2419 2420 if (x == y) 2421 { 2422 q(); 2423 } 2424 else if (x > y) 2425 { 2426 w(); 2427 } 2428 else 2429 { 2430 r(); 2431 } 2432 } 2433