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