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 <http://www.chromium.org/developers/coding-style>`_ 141 * ``Mozilla`` 142 A style complying with `Mozilla's style guide 143 <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_ 144 * ``WebKit`` 145 A style complying with `WebKit's style guide 146 <http://www.webkit.org/coding/coding-style.html>`_ 147 148.. START_FORMAT_STYLE_OPTIONS 149 150**AccessModifierOffset** (``int``) 151 The extra indent or outdent of access modifiers, e.g. ``public:``. 152 153**AlignAfterOpenBracket** (``BracketAlignmentStyle``) 154 If ``true``, horizontally aligns arguments after an open bracket. 155 156 This applies to round brackets (parentheses), angle brackets and square 157 brackets. 158 159 Possible values: 160 161 * ``BAS_Align`` (in configuration: ``Align``) 162 Align parameters on the open bracket, e.g.: 163 164 .. code-block:: c++ 165 166 someLongFunction(argument1, 167 argument2); 168 169 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 170 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 171 172 .. code-block:: c++ 173 174 someLongFunction(argument1, 175 argument2); 176 177 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 178 Always break after an open bracket, if the parameters don't fit 179 on a single line, e.g.: 180 181 .. code-block:: c++ 182 183 someLongFunction( 184 argument1, argument2); 185 186 187 188**AlignConsecutiveAssignments** (``bool``) 189 If ``true``, aligns consecutive assignments. 190 191 This will align the assignment operators of consecutive lines. This 192 will result in formattings like 193 194 .. code-block:: c++ 195 196 int aaaa = 12; 197 int b = 23; 198 int ccc = 23; 199 200**AlignConsecutiveDeclarations** (``bool``) 201 If ``true``, aligns consecutive declarations. 202 203 This will align the declaration names of consecutive lines. This 204 will result in formattings like 205 206 .. code-block:: c++ 207 208 int aaaa = 12; 209 float b = 23; 210 std::string ccc = 23; 211 212**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 foo(); 930 } 931 catch () { 932 } 933 void foo() { bar(); } 934 class foo { 935 }; 936 if (foo()) { 937 } 938 else { 939 } 940 enum X : int { A, B }; 941 942 * ``BS_GNU`` (in configuration: ``GNU``) 943 Always break before braces and add an extra level of indentation to 944 braces of control statements, not to those of class, function 945 or other definitions. 946 947 .. code-block:: c++ 948 949 try 950 { 951 foo(); 952 } 953 catch () 954 { 955 } 956 void foo() { bar(); } 957 class foo 958 { 959 }; 960 if (foo()) 961 { 962 } 963 else 964 { 965 } 966 enum X : int 967 { 968 A, 969 B 970 }; 971 972 * ``BS_WebKit`` (in configuration: ``WebKit``) 973 Like ``Attach``, but break before functions. 974 975 .. code-block:: c++ 976 977 try { 978 foo(); 979 } catch () { 980 } 981 void foo() { bar(); } 982 class foo { 983 }; 984 if (foo()) { 985 } else { 986 } 987 enum X : int { A, B }; 988 989 * ``BS_Custom`` (in configuration: ``Custom``) 990 Configure each individual brace in `BraceWrapping`. 991 992 993 994**BreakBeforeTernaryOperators** (``bool``) 995 If ``true``, ternary operators will be placed after line breaks. 996 997 .. code-block:: c++ 998 999 true: 1000 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription 1001 ? firstValue 1002 : SecondValueVeryVeryVeryVeryLong; 1003 1004 false: 1005 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? 1006 firstValue : 1007 SecondValueVeryVeryVeryVeryLong; 1008 1009**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) 1010 The constructor initializers style to use. 1011 1012 Possible values: 1013 1014 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) 1015 Break constructor initializers before the colon and after the commas. 1016 1017 .. code-block:: c++ 1018 1019 Constructor() 1020 : initializer1(), 1021 initializer2() 1022 1023 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) 1024 Break constructor initializers before the colon and commas, and align 1025 the commas with the colon. 1026 1027 .. code-block:: c++ 1028 1029 Constructor() 1030 : initializer1() 1031 , initializer2() 1032 1033 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) 1034 Break constructor initializers after the colon and commas. 1035 1036 .. code-block:: c++ 1037 1038 Constructor() : 1039 initializer1(), 1040 initializer2() 1041 1042 1043 1044**BreakInheritanceList** (``BreakInheritanceListStyle``) 1045 The inheritance list style to use. 1046 1047 Possible values: 1048 1049 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) 1050 Break inheritance list before the colon and after the commas. 1051 1052 .. code-block:: c++ 1053 1054 class Foo 1055 : Base1, 1056 Base2 1057 {}; 1058 1059 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) 1060 Break inheritance list before the colon and commas, and align 1061 the commas with the colon. 1062 1063 .. code-block:: c++ 1064 1065 class Foo 1066 : Base1 1067 , Base2 1068 {}; 1069 1070 * ``BILS_AfterColon`` (in configuration: ``AfterColon``) 1071 Break inheritance list after the colon and commas. 1072 1073 .. code-block:: c++ 1074 1075 class Foo : 1076 Base1, 1077 Base2 1078 {}; 1079 1080 1081 1082**BreakStringLiterals** (``bool``) 1083 Allow breaking string literals when formatting. 1084 1085**ColumnLimit** (``unsigned``) 1086 The column limit. 1087 1088 A column limit of ``0`` means that there is no column limit. In this case, 1089 clang-format will respect the input's line breaking decisions within 1090 statements unless they contradict other rules. 1091 1092**CommentPragmas** (``std::string``) 1093 A regular expression that describes comments with special meaning, 1094 which should not be split into lines or otherwise changed. 1095 1096 .. code-block:: c++ 1097 1098 // CommentPragmas: '^ FOOBAR pragma:' 1099 // Will leave the following line unaffected 1100 #include <vector> // FOOBAR pragma: keep 1101 1102**CompactNamespaces** (``bool``) 1103 If ``true``, consecutive namespace declarations will be on the same 1104 line. If ``false``, each namespace is declared on a new line. 1105 1106 .. code-block:: c++ 1107 1108 true: 1109 namespace Foo { namespace Bar { 1110 }} 1111 1112 false: 1113 namespace Foo { 1114 namespace Bar { 1115 } 1116 } 1117 1118 If it does not fit on a single line, the overflowing namespaces get 1119 wrapped: 1120 1121 .. code-block:: c++ 1122 1123 namespace Foo { namespace Bar { 1124 namespace Extra { 1125 }}} 1126 1127**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) 1128 If the constructor initializers don't fit on a line, put each 1129 initializer on its own line. 1130 1131 .. code-block:: c++ 1132 1133 true: 1134 SomeClass::Constructor() 1135 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 1136 return 0; 1137 } 1138 1139 false: 1140 SomeClass::Constructor() 1141 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), 1142 aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 1143 return 0; 1144 } 1145 1146**ConstructorInitializerIndentWidth** (``unsigned``) 1147 The number of characters to use for indentation of constructor 1148 initializer lists as well as inheritance lists. 1149 1150**ContinuationIndentWidth** (``unsigned``) 1151 Indent width for line continuations. 1152 1153 .. code-block:: c++ 1154 1155 ContinuationIndentWidth: 2 1156 1157 int i = // VeryVeryVeryVeryVeryLongComment 1158 longFunction( // Again a long comment 1159 arg); 1160 1161**Cpp11BracedListStyle** (``bool``) 1162 If ``true``, format braced lists as best suited for C++11 braced 1163 lists. 1164 1165 Important differences: 1166 - No spaces inside the braced list. 1167 - No line break before the closing brace. 1168 - Indentation with the continuation indent, not with the block indent. 1169 1170 Fundamentally, C++11 braced lists are formatted exactly like function 1171 calls would be formatted in their place. If the braced list follows a name 1172 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 1173 the parentheses of a function call with that name. If there is no name, 1174 a zero-length name is assumed. 1175 1176 .. code-block:: c++ 1177 1178 true: false: 1179 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 }; 1180 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} }; 1181 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); 1182 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; 1183 1184**DerivePointerAlignment** (``bool``) 1185 If ``true``, analyze the formatted file for the most common 1186 alignment of ``&`` and ``*``. 1187 Pointer and reference alignment styles are going to be updated according 1188 to the preferences found in the file. 1189 ``PointerAlignment`` is then used only as fallback. 1190 1191**DisableFormat** (``bool``) 1192 Disables formatting completely. 1193 1194**ExperimentalAutoDetectBinPacking** (``bool``) 1195 If ``true``, clang-format detects whether function calls and 1196 definitions are formatted with one parameter per line. 1197 1198 Each call can be bin-packed, one-per-line or inconclusive. If it is 1199 inconclusive, e.g. completely on one line, but a decision needs to be 1200 made, clang-format analyzes whether there are other bin-packed cases in 1201 the input file and act accordingly. 1202 1203 NOTE: This is an experimental flag, that might go away or be renamed. Do 1204 not use this in config files, etc. Use at your own risk. 1205 1206**FixNamespaceComments** (``bool``) 1207 If ``true``, clang-format adds missing namespace end comments and 1208 fixes invalid existing ones. 1209 1210 .. code-block:: c++ 1211 1212 true: false: 1213 namespace a { vs. namespace a { 1214 foo(); foo(); 1215 } // namespace a; } 1216 1217**ForEachMacros** (``std::vector<std::string>``) 1218 A vector of macros that should be interpreted as foreach loops 1219 instead of as function calls. 1220 1221 These are expected to be macros of the form: 1222 1223 .. code-block:: c++ 1224 1225 FOREACH(<variable-declaration>, ...) 1226 <loop-body> 1227 1228 In the .clang-format configuration file, this can be configured like: 1229 1230 .. code-block:: yaml 1231 1232 ForEachMacros: ['RANGES_FOR', 'FOREACH'] 1233 1234 For example: BOOST_FOREACH. 1235 1236**IncludeBlocks** (``IncludeBlocksStyle``) 1237 Dependent on the value, multiple ``#include`` blocks can be sorted 1238 as one and divided based on category. 1239 1240 Possible values: 1241 1242 * ``IBS_Preserve`` (in configuration: ``Preserve``) 1243 Sort each ``#include`` block separately. 1244 1245 .. code-block:: c++ 1246 1247 #include "b.h" into #include "b.h" 1248 1249 #include <lib/main.h> #include "a.h" 1250 #include "a.h" #include <lib/main.h> 1251 1252 * ``IBS_Merge`` (in configuration: ``Merge``) 1253 Merge multiple ``#include`` blocks together and sort as one. 1254 1255 .. code-block:: c++ 1256 1257 #include "b.h" into #include "a.h" 1258 #include "b.h" 1259 #include <lib/main.h> #include <lib/main.h> 1260 #include "a.h" 1261 1262 * ``IBS_Regroup`` (in configuration: ``Regroup``) 1263 Merge multiple ``#include`` blocks together and sort as one. 1264 Then split into groups based on category priority. See 1265 ``IncludeCategories``. 1266 1267 .. code-block:: c++ 1268 1269 #include "b.h" into #include "a.h" 1270 #include "b.h" 1271 #include <lib/main.h> 1272 #include "a.h" #include <lib/main.h> 1273 1274 1275 1276**IncludeCategories** (``std::vector<IncludeCategory>``) 1277 Regular expressions denoting the different ``#include`` categories 1278 used for ordering ``#includes``. 1279 1280 `POSIX extended 1281 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ 1282 regular expressions are supported. 1283 1284 These regular expressions are matched against the filename of an include 1285 (including the <> or "") in order. The value belonging to the first 1286 matching regular expression is assigned and ``#includes`` are sorted first 1287 according to increasing category number and then alphabetically within 1288 each category. 1289 1290 If none of the regular expressions match, INT_MAX is assigned as 1291 category. The main header for a source file automatically gets category 0. 1292 so that it is generally kept at the beginning of the ``#includes`` 1293 (https://llvm.org/docs/CodingStandards.html#include-style). However, you 1294 can also assign negative priorities if you have certain headers that 1295 always need to be first. 1296 1297 To configure this in the .clang-format file, use: 1298 1299 .. code-block:: yaml 1300 1301 IncludeCategories: 1302 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 1303 Priority: 2 1304 - Regex: '^(<|"(gtest|gmock|isl|json)/)' 1305 Priority: 3 1306 - Regex: '<[[:alnum:].]+>' 1307 Priority: 4 1308 - Regex: '.*' 1309 Priority: 1 1310 1311**IncludeIsMainRegex** (``std::string``) 1312 Specify a regular expression of suffixes that are allowed in the 1313 file-to-main-include mapping. 1314 1315 When guessing whether a #include is the "main" include (to assign 1316 category 0, see above), use this regex of allowed suffixes to the header 1317 stem. A partial match is done, so that: 1318 - "" means "arbitrary suffix" 1319 - "$" means "no suffix" 1320 1321 For example, if configured to "(_test)?$", then a header a.h would be seen 1322 as the "main" include in both a.cc and a_test.cc. 1323 1324**IndentCaseLabels** (``bool``) 1325 Indent case labels one level from the switch statement. 1326 1327 When ``false``, use the same indentation level as for the switch statement. 1328 Switch statement body is always indented one level more than case labels. 1329 1330 .. code-block:: c++ 1331 1332 false: true: 1333 switch (fool) { vs. switch (fool) { 1334 case 1: case 1: 1335 bar(); bar(); 1336 break; break; 1337 default: default: 1338 plop(); plop(); 1339 } } 1340 1341**IndentPPDirectives** (``PPDirectiveIndentStyle``) 1342 The preprocessor directive indenting style to use. 1343 1344 Possible values: 1345 1346 * ``PPDIS_None`` (in configuration: ``None``) 1347 Does not indent any directives. 1348 1349 .. code-block:: c++ 1350 1351 #if FOO 1352 #if BAR 1353 #include <foo> 1354 #endif 1355 #endif 1356 1357 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``) 1358 Indents directives after the hash. 1359 1360 .. code-block:: c++ 1361 1362 #if FOO 1363 # if BAR 1364 # include <foo> 1365 # endif 1366 #endif 1367 1368 1369 1370**IndentWidth** (``unsigned``) 1371 The number of columns to use for indentation. 1372 1373 .. code-block:: c++ 1374 1375 IndentWidth: 3 1376 1377 void f() { 1378 someFunction(); 1379 if (true, false) { 1380 f(); 1381 } 1382 } 1383 1384**IndentWrappedFunctionNames** (``bool``) 1385 Indent if a function definition or declaration is wrapped after the 1386 type. 1387 1388 .. code-block:: c++ 1389 1390 true: 1391 LoooooooooooooooooooooooooooooooooooooooongReturnType 1392 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 1393 1394 false: 1395 LoooooooooooooooooooooooooooooooooooooooongReturnType 1396 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 1397 1398**JavaImportGroups** (``std::vector<std::string>``) 1399 A vector of prefixes ordered by the desired groups for Java imports. 1400 1401 Each group is seperated by a newline. Static imports will also follow the 1402 same grouping convention above all non-static imports. One group's prefix 1403 can be a subset of another - the longest prefix is always matched. Within 1404 a group, the imports are ordered lexicographically. 1405 1406 In the .clang-format configuration file, this can be configured like 1407 in the following yaml example. This will result in imports being 1408 formatted as in the Java example below. 1409 1410 .. code-block:: yaml 1411 1412 JavaImportGroups: ['com.example', 'com', 'org'] 1413 1414 1415 .. code-block:: java 1416 1417 import static com.example.function1; 1418 1419 import static com.test.function2; 1420 1421 import static org.example.function3; 1422 1423 import com.example.ClassA; 1424 import com.example.Test; 1425 import com.example.a.ClassB; 1426 1427 import com.test.ClassC; 1428 1429 import org.example.ClassD; 1430 1431**JavaScriptQuotes** (``JavaScriptQuoteStyle``) 1432 The JavaScriptQuoteStyle to use for JavaScript strings. 1433 1434 Possible values: 1435 1436 * ``JSQS_Leave`` (in configuration: ``Leave``) 1437 Leave string quotes as they are. 1438 1439 .. code-block:: js 1440 1441 string1 = "foo"; 1442 string2 = 'bar'; 1443 1444 * ``JSQS_Single`` (in configuration: ``Single``) 1445 Always use single quotes. 1446 1447 .. code-block:: js 1448 1449 string1 = 'foo'; 1450 string2 = 'bar'; 1451 1452 * ``JSQS_Double`` (in configuration: ``Double``) 1453 Always use double quotes. 1454 1455 .. code-block:: js 1456 1457 string1 = "foo"; 1458 string2 = "bar"; 1459 1460 1461 1462**JavaScriptWrapImports** (``bool``) 1463 Whether to wrap JavaScript import/export statements. 1464 1465 .. code-block:: js 1466 1467 true: 1468 import { 1469 VeryLongImportsAreAnnoying, 1470 VeryLongImportsAreAnnoying, 1471 VeryLongImportsAreAnnoying, 1472 } from 'some/module.js' 1473 1474 false: 1475 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" 1476 1477**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) 1478 If true, the empty line at the start of blocks is kept. 1479 1480 .. code-block:: c++ 1481 1482 true: false: 1483 if (foo) { vs. if (foo) { 1484 bar(); 1485 bar(); } 1486 } 1487 1488**Language** (``LanguageKind``) 1489 Language, this format style is targeted at. 1490 1491 Possible values: 1492 1493 * ``LK_None`` (in configuration: ``None``) 1494 Do not use. 1495 1496 * ``LK_Cpp`` (in configuration: ``Cpp``) 1497 Should be used for C, C++. 1498 1499 * ``LK_Java`` (in configuration: ``Java``) 1500 Should be used for Java. 1501 1502 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 1503 Should be used for JavaScript. 1504 1505 * ``LK_ObjC`` (in configuration: ``ObjC``) 1506 Should be used for Objective-C, Objective-C++. 1507 1508 * ``LK_Proto`` (in configuration: ``Proto``) 1509 Should be used for Protocol Buffers 1510 (https://developers.google.com/protocol-buffers/). 1511 1512 * ``LK_TableGen`` (in configuration: ``TableGen``) 1513 Should be used for TableGen code. 1514 1515 * ``LK_TextProto`` (in configuration: ``TextProto``) 1516 Should be used for Protocol Buffer messages in text format 1517 (https://developers.google.com/protocol-buffers/). 1518 1519 1520 1521**MacroBlockBegin** (``std::string``) 1522 A regular expression matching macros that start a block. 1523 1524 .. code-block:: c++ 1525 1526 # With: 1527 MacroBlockBegin: "^NS_MAP_BEGIN|\ 1528 NS_TABLE_HEAD$" 1529 MacroBlockEnd: "^\ 1530 NS_MAP_END|\ 1531 NS_TABLE_.*_END$" 1532 1533 NS_MAP_BEGIN 1534 foo(); 1535 NS_MAP_END 1536 1537 NS_TABLE_HEAD 1538 bar(); 1539 NS_TABLE_FOO_END 1540 1541 # Without: 1542 NS_MAP_BEGIN 1543 foo(); 1544 NS_MAP_END 1545 1546 NS_TABLE_HEAD 1547 bar(); 1548 NS_TABLE_FOO_END 1549 1550**MacroBlockEnd** (``std::string``) 1551 A regular expression matching macros that end a block. 1552 1553**MaxEmptyLinesToKeep** (``unsigned``) 1554 The maximum number of consecutive empty lines to keep. 1555 1556 .. code-block:: c++ 1557 1558 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 1559 int f() { int f() { 1560 int = 1; int i = 1; 1561 i = foo(); 1562 i = foo(); return i; 1563 } 1564 return i; 1565 } 1566 1567**NamespaceIndentation** (``NamespaceIndentationKind``) 1568 The indentation used for namespaces. 1569 1570 Possible values: 1571 1572 * ``NI_None`` (in configuration: ``None``) 1573 Don't indent in namespaces. 1574 1575 .. code-block:: c++ 1576 1577 namespace out { 1578 int i; 1579 namespace in { 1580 int i; 1581 } 1582 } 1583 1584 * ``NI_Inner`` (in configuration: ``Inner``) 1585 Indent only in inner namespaces (nested in other namespaces). 1586 1587 .. code-block:: c++ 1588 1589 namespace out { 1590 int i; 1591 namespace in { 1592 int i; 1593 } 1594 } 1595 1596 * ``NI_All`` (in configuration: ``All``) 1597 Indent in all namespaces. 1598 1599 .. code-block:: c++ 1600 1601 namespace out { 1602 int i; 1603 namespace in { 1604 int i; 1605 } 1606 } 1607 1608 1609 1610**ObjCBinPackProtocolList** (``BinPackStyle``) 1611 Controls bin-packing Objective-C protocol conformance list 1612 items into as few lines as possible when they go over ``ColumnLimit``. 1613 1614 If ``Auto`` (the default), delegates to the value in 1615 ``BinPackParameters``. If that is ``true``, bin-packs Objective-C 1616 protocol conformance list items into as few lines as possible 1617 whenever they go over ``ColumnLimit``. 1618 1619 If ``Always``, always bin-packs Objective-C protocol conformance 1620 list items into as few lines as possible whenever they go over 1621 ``ColumnLimit``. 1622 1623 If ``Never``, lays out Objective-C protocol conformance list items 1624 onto individual lines whenever they go over ``ColumnLimit``. 1625 1626 1627 .. code-block:: objc 1628 1629 Always (or Auto, if BinPackParameters=true): 1630 @interface ccccccccccccc () < 1631 ccccccccccccc, ccccccccccccc, 1632 ccccccccccccc, ccccccccccccc> { 1633 } 1634 1635 Never (or Auto, if BinPackParameters=false): 1636 @interface ddddddddddddd () < 1637 ddddddddddddd, 1638 ddddddddddddd, 1639 ddddddddddddd, 1640 ddddddddddddd> { 1641 } 1642 1643 Possible values: 1644 1645 * ``BPS_Auto`` (in configuration: ``Auto``) 1646 Automatically determine parameter bin-packing behavior. 1647 1648 * ``BPS_Always`` (in configuration: ``Always``) 1649 Always bin-pack parameters. 1650 1651 * ``BPS_Never`` (in configuration: ``Never``) 1652 Never bin-pack parameters. 1653 1654 1655 1656**ObjCBlockIndentWidth** (``unsigned``) 1657 The number of characters to use for indentation of ObjC blocks. 1658 1659 .. code-block:: objc 1660 1661 ObjCBlockIndentWidth: 4 1662 1663 [operation setCompletionBlock:^{ 1664 [self onOperationDone]; 1665 }]; 1666 1667**ObjCSpaceAfterProperty** (``bool``) 1668 Add a space after ``@property`` in Objective-C, i.e. use 1669 ``@property (readonly)`` instead of ``@property(readonly)``. 1670 1671**ObjCSpaceBeforeProtocolList** (``bool``) 1672 Add a space in front of an Objective-C protocol list, i.e. use 1673 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 1674 1675**PenaltyBreakAssignment** (``unsigned``) 1676 The penalty for breaking around an assignment operator. 1677 1678**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) 1679 The penalty for breaking a function call after ``call(``. 1680 1681**PenaltyBreakComment** (``unsigned``) 1682 The penalty for each line break introduced inside a comment. 1683 1684**PenaltyBreakFirstLessLess** (``unsigned``) 1685 The penalty for breaking before the first ``<<``. 1686 1687**PenaltyBreakString** (``unsigned``) 1688 The penalty for each line break introduced inside a string literal. 1689 1690**PenaltyBreakTemplateDeclaration** (``unsigned``) 1691 The penalty for breaking after template declaration. 1692 1693**PenaltyExcessCharacter** (``unsigned``) 1694 The penalty for each character outside of the column limit. 1695 1696**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) 1697 Penalty for putting the return type of a function onto its own 1698 line. 1699 1700**PointerAlignment** (``PointerAlignmentStyle``) 1701 Pointer and reference alignment style. 1702 1703 Possible values: 1704 1705 * ``PAS_Left`` (in configuration: ``Left``) 1706 Align pointer to the left. 1707 1708 .. code-block:: c++ 1709 1710 int* a; 1711 1712 * ``PAS_Right`` (in configuration: ``Right``) 1713 Align pointer to the right. 1714 1715 .. code-block:: c++ 1716 1717 int *a; 1718 1719 * ``PAS_Middle`` (in configuration: ``Middle``) 1720 Align pointer in the middle. 1721 1722 .. code-block:: c++ 1723 1724 int * a; 1725 1726 1727 1728**RawStringFormats** (``std::vector<RawStringFormat>``) 1729 Defines hints for detecting supported languages code blocks in raw 1730 strings. 1731 1732 A raw string with a matching delimiter or a matching enclosing function 1733 name will be reformatted assuming the specified language based on the 1734 style for that language defined in the .clang-format file. If no style has 1735 been defined in the .clang-format file for the specific language, a 1736 predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not 1737 found, the formatting is based on llvm style. A matching delimiter takes 1738 precedence over a matching enclosing function name for determining the 1739 language of the raw string contents. 1740 1741 If a canonical delimiter is specified, occurrences of other delimiters for 1742 the same language will be updated to the canonical if possible. 1743 1744 There should be at most one specification per language and each delimiter 1745 and enclosing function should not occur in multiple specifications. 1746 1747 To configure this in the .clang-format file, use: 1748 1749 .. code-block:: yaml 1750 1751 RawStringFormats: 1752 - Language: TextProto 1753 Delimiters: 1754 - 'pb' 1755 - 'proto' 1756 EnclosingFunctions: 1757 - 'PARSE_TEXT_PROTO' 1758 BasedOnStyle: google 1759 - Language: Cpp 1760 Delimiters: 1761 - 'cc' 1762 - 'cpp' 1763 BasedOnStyle: llvm 1764 CanonicalDelimiter: 'cc' 1765 1766**ReflowComments** (``bool``) 1767 If ``true``, clang-format will attempt to re-flow comments. 1768 1769 .. code-block:: c++ 1770 1771 false: 1772 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 1773 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 1774 1775 true: 1776 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 1777 // information 1778 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 1779 * information */ 1780 1781**SortIncludes** (``bool``) 1782 If ``true``, clang-format will sort ``#includes``. 1783 1784 .. code-block:: c++ 1785 1786 false: true: 1787 #include "b.h" vs. #include "a.h" 1788 #include "a.h" #include "b.h" 1789 1790**SortUsingDeclarations** (``bool``) 1791 If ``true``, clang-format will sort using declarations. 1792 1793 The order of using declarations is defined as follows: 1794 Split the strings by "::" and discard any initial empty strings. The last 1795 element of each list is a non-namespace name; all others are namespace 1796 names. Sort the lists of names lexicographically, where the sort order of 1797 individual names is that all non-namespace names come before all namespace 1798 names, and within those groups, names are in case-insensitive 1799 lexicographic order. 1800 1801 .. code-block:: c++ 1802 1803 false: true: 1804 using std::cout; vs. using std::cin; 1805 using std::cin; using std::cout; 1806 1807**SpaceAfterCStyleCast** (``bool``) 1808 If ``true``, a space is inserted after C style casts. 1809 1810 .. code-block:: c++ 1811 1812 true: false: 1813 (int) i; vs. (int)i; 1814 1815**SpaceAfterTemplateKeyword** (``bool``) 1816 If ``true``, a space will be inserted after the 'template' keyword. 1817 1818 .. code-block:: c++ 1819 1820 true: false: 1821 template <int> void foo(); vs. template<int> void foo(); 1822 1823**SpaceBeforeAssignmentOperators** (``bool``) 1824 If ``false``, spaces will be removed before assignment operators. 1825 1826 .. code-block:: c++ 1827 1828 true: false: 1829 int a = 5; vs. int a=5; 1830 a += 42 a+=42; 1831 1832**SpaceBeforeCpp11BracedList** (``bool``) 1833 If ``true``, a space will be inserted before a C++11 braced list 1834 used to initialize an object (after the preceding identifier or type). 1835 1836 .. code-block:: c++ 1837 1838 true: false: 1839 Foo foo { bar }; vs. Foo foo{ bar }; 1840 Foo {}; Foo{}; 1841 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; 1842 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; 1843 1844**SpaceBeforeCtorInitializerColon** (``bool``) 1845 If ``false``, spaces will be removed before constructor initializer 1846 colon. 1847 1848 .. code-block:: c++ 1849 1850 true: false: 1851 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} 1852 1853**SpaceBeforeInheritanceColon** (``bool``) 1854 If ``false``, spaces will be removed before inheritance colon. 1855 1856 .. code-block:: c++ 1857 1858 true: false: 1859 class Foo : Bar {} vs. class Foo: Bar {} 1860 1861**SpaceBeforeParens** (``SpaceBeforeParensOptions``) 1862 Defines in which cases to put a space before opening parentheses. 1863 1864 Possible values: 1865 1866 * ``SBPO_Never`` (in configuration: ``Never``) 1867 Never put a space before opening parentheses. 1868 1869 .. code-block:: c++ 1870 1871 void f() { 1872 if(true) { 1873 f(); 1874 } 1875 } 1876 1877 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 1878 Put a space before opening parentheses only after control statement 1879 keywords (``for/if/while...``). 1880 1881 .. code-block:: c++ 1882 1883 void f() { 1884 if (true) { 1885 f(); 1886 } 1887 } 1888 1889 * ``SBPO_Always`` (in configuration: ``Always``) 1890 Always put a space before opening parentheses, except when it's 1891 prohibited by the syntax rules (in function-like macro definitions) or 1892 when determined by other style rules (after unary operators, opening 1893 parentheses, etc.) 1894 1895 .. code-block:: c++ 1896 1897 void f () { 1898 if (true) { 1899 f (); 1900 } 1901 } 1902 1903 1904 1905**SpaceBeforeRangeBasedForLoopColon** (``bool``) 1906 If ``false``, spaces will be removed before range-based for loop 1907 colon. 1908 1909 .. code-block:: c++ 1910 1911 true: false: 1912 for (auto v : values) {} vs. for(auto v: values) {} 1913 1914**SpaceInEmptyParentheses** (``bool``) 1915 If ``true``, spaces may be inserted into ``()``. 1916 1917 .. code-block:: c++ 1918 1919 true: false: 1920 void f( ) { vs. void f() { 1921 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; 1922 if (true) { if (true) { 1923 f( ); f(); 1924 } } 1925 } } 1926 1927**SpacesBeforeTrailingComments** (``unsigned``) 1928 The number of spaces before trailing line comments 1929 (``//`` - comments). 1930 1931 This does not affect trailing block comments (``/*`` - comments) as 1932 those commonly have different usage patterns and a number of special 1933 cases. 1934 1935 .. code-block:: c++ 1936 1937 SpacesBeforeTrailingComments: 3 1938 void f() { 1939 if (true) { // foo1 1940 f(); // bar 1941 } // foo 1942 } 1943 1944**SpacesInAngles** (``bool``) 1945 If ``true``, spaces will be inserted after ``<`` and before ``>`` 1946 in template argument lists. 1947 1948 .. code-block:: c++ 1949 1950 true: false: 1951 static_cast< int >(arg); vs. static_cast<int>(arg); 1952 std::function< void(int) > fct; std::function<void(int)> fct; 1953 1954**SpacesInCStyleCastParentheses** (``bool``) 1955 If ``true``, spaces may be inserted into C style casts. 1956 1957 .. code-block:: c++ 1958 1959 true: false: 1960 x = ( int32 )y vs. x = (int32)y 1961 1962**SpacesInContainerLiterals** (``bool``) 1963 If ``true``, spaces are inserted inside container literals (e.g. 1964 ObjC and Javascript array and dict literals). 1965 1966 .. code-block:: js 1967 1968 true: false: 1969 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; 1970 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); 1971 1972**SpacesInParentheses** (``bool``) 1973 If ``true``, spaces will be inserted after ``(`` and before ``)``. 1974 1975 .. code-block:: c++ 1976 1977 true: false: 1978 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; 1979 1980**SpacesInSquareBrackets** (``bool``) 1981 If ``true``, spaces will be inserted after ``[`` and before ``]``. 1982 Lambdas or unspecified size array declarations will not be affected. 1983 1984 .. code-block:: c++ 1985 1986 true: false: 1987 int a[ 5 ]; vs. int a[5]; 1988 std::unique_ptr<int[]> foo() {} // Won't be affected 1989 1990**Standard** (``LanguageStandard``) 1991 Format compatible with this standard, e.g. use ``A<A<int> >`` 1992 instead of ``A<A<int>>`` for ``LS_Cpp03``. 1993 1994 Possible values: 1995 1996 * ``LS_Cpp03`` (in configuration: ``Cpp03``) 1997 Use C++03-compatible syntax. 1998 1999 * ``LS_Cpp11`` (in configuration: ``Cpp11``) 2000 Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of 2001 ``A<A<int> >``). 2002 2003 * ``LS_Auto`` (in configuration: ``Auto``) 2004 Automatic detection based on the input. 2005 2006 2007 2008**StatementMacros** (``std::vector<std::string>``) 2009 A vector of macros that should be interpreted as complete 2010 statements. 2011 2012 Typical macros are expressions, and require a semi-colon to be 2013 added; sometimes this is not the case, and this allows to make 2014 clang-format aware of such cases. 2015 2016 For example: Q_UNUSED 2017 2018**TabWidth** (``unsigned``) 2019 The number of columns used for tab stops. 2020 2021**UseTab** (``UseTabStyle``) 2022 The way to use tab characters in the resulting file. 2023 2024 Possible values: 2025 2026 * ``UT_Never`` (in configuration: ``Never``) 2027 Never use tab. 2028 2029 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 2030 Use tabs only for indentation. 2031 2032 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``) 2033 Use tabs only for line continuation and indentation. 2034 2035 * ``UT_Always`` (in configuration: ``Always``) 2036 Use tabs whenever we need to fill whitespace that spans at least from 2037 one tab stop to the next one. 2038 2039 2040 2041.. END_FORMAT_STYLE_OPTIONS 2042 2043Adding additional style options 2044=============================== 2045 2046Each additional style option adds costs to the clang-format project. Some of 2047these costs affect the clang-format development itself, as we need to make 2048sure that any given combination of options work and that new features don't 2049break any of the existing options in any way. There are also costs for end users 2050as options become less discoverable and people have to think about and make a 2051decision on options they don't really care about. 2052 2053The goal of the clang-format project is more on the side of supporting a 2054limited set of styles really well as opposed to supporting every single style 2055used by a codebase somewhere in the wild. Of course, we do want to support all 2056major projects and thus have established the following bar for adding style 2057options. Each new style option must .. 2058 2059 * be used in a project of significant size (have dozens of contributors) 2060 * have a publicly accessible style guide 2061 * have a person willing to contribute and maintain patches 2062 2063Examples 2064======== 2065 2066A style similar to the `Linux Kernel style 2067<https://www.kernel.org/doc/Documentation/CodingStyle>`_: 2068 2069.. code-block:: yaml 2070 2071 BasedOnStyle: LLVM 2072 IndentWidth: 8 2073 UseTab: Always 2074 BreakBeforeBraces: Linux 2075 AllowShortIfStatementsOnASingleLine: false 2076 IndentCaseLabels: false 2077 2078The result is (imagine that tabs are used for indentation here): 2079 2080.. code-block:: c++ 2081 2082 void test() 2083 { 2084 switch (x) { 2085 case 0: 2086 case 1: 2087 do_something(); 2088 break; 2089 case 2: 2090 do_something_else(); 2091 break; 2092 default: 2093 break; 2094 } 2095 if (condition) 2096 do_something_completely_different(); 2097 2098 if (x == y) { 2099 q(); 2100 } else if (x > y) { 2101 w(); 2102 } else { 2103 r(); 2104 } 2105 } 2106 2107A style similar to the default Visual Studio formatting style: 2108 2109.. code-block:: yaml 2110 2111 UseTab: Never 2112 IndentWidth: 4 2113 BreakBeforeBraces: Allman 2114 AllowShortIfStatementsOnASingleLine: false 2115 IndentCaseLabels: false 2116 ColumnLimit: 0 2117 2118The result is: 2119 2120.. code-block:: c++ 2121 2122 void test() 2123 { 2124 switch (suffix) 2125 { 2126 case 0: 2127 case 1: 2128 do_something(); 2129 break; 2130 case 2: 2131 do_something_else(); 2132 break; 2133 default: 2134 break; 2135 } 2136 if (condition) 2137 do_somthing_completely_different(); 2138 2139 if (x == y) 2140 { 2141 q(); 2142 } 2143 else if (x > y) 2144 { 2145 w(); 2146 } 2147 else 2148 { 2149 r(); 2150 } 2151 } 2152