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