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