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