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 languages. 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 * ``GNU`` 155 A style complying with the `GNU coding standards 156 <https://www.gnu.org/prep/standards/standards.html>`_ 157 * ``InheritParentConfig`` 158 Not a real style, but allows to use the ``.clang-format`` file from the 159 parent directory (or its parent if there is none). If there is no parent 160 file found it falls back to the ``fallback`` style, and applies the changes 161 to that. 162 163 With this option you can overwrite some parts of your main style for your 164 subdirectories. This is also possible through the command line, e.g.: 165 ``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}`` 166 167.. START_FORMAT_STYLE_OPTIONS 168 169**AccessModifierOffset** (``int``) 170 The extra indent or outdent of access modifiers, e.g. ``public:``. 171 172**AlignAfterOpenBracket** (``BracketAlignmentStyle``) 173 If ``true``, horizontally aligns arguments after an open bracket. 174 175 This applies to round brackets (parentheses), angle brackets and square 176 brackets. 177 178 Possible values: 179 180 * ``BAS_Align`` (in configuration: ``Align``) 181 Align parameters on the open bracket, e.g.: 182 183 .. code-block:: c++ 184 185 someLongFunction(argument1, 186 argument2); 187 188 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 189 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 190 191 .. code-block:: c++ 192 193 someLongFunction(argument1, 194 argument2); 195 196 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 197 Always break after an open bracket, if the parameters don't fit 198 on a single line, e.g.: 199 200 .. code-block:: c++ 201 202 someLongFunction( 203 argument1, argument2); 204 205 206 207**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) 208 Style of aligning consecutive assignments. 209 210 ``Consecutive`` will result in formattings like: 211 212 .. code-block:: c++ 213 214 int a = 1; 215 int somelongname = 2; 216 double c = 3; 217 218 Possible values: 219 220 * ``ACS_None`` (in configuration: ``None``) 221 Do not align assignments on consecutive lines. 222 223 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 224 Align assignments on consecutive lines. This will result in 225 formattings like: 226 227 .. code-block:: c++ 228 229 int a = 1; 230 int somelongname = 2; 231 double c = 3; 232 233 int d = 3; 234 /* A comment. */ 235 double e = 4; 236 237 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 238 Same as ACS_Consecutive, but also spans over empty lines, e.g. 239 240 .. code-block:: c++ 241 242 int a = 1; 243 int somelongname = 2; 244 double c = 3; 245 246 int d = 3; 247 /* A comment. */ 248 double e = 4; 249 250 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 251 Same as ACS_Consecutive, but also spans over lines only containing 252 comments, e.g. 253 254 .. code-block:: c++ 255 256 int a = 1; 257 int somelongname = 2; 258 double c = 3; 259 260 int d = 3; 261 /* A comment. */ 262 double e = 4; 263 264 * ``ACS_AcrossEmptyLinesAndComments`` 265 (in configuration: ``AcrossEmptyLinesAndComments``) 266 267 Same as ACS_Consecutive, but also spans over lines only containing 268 comments and empty lines, e.g. 269 270 .. code-block:: c++ 271 272 int a = 1; 273 int somelongname = 2; 274 double c = 3; 275 276 int d = 3; 277 /* A comment. */ 278 double e = 4; 279 280**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) 281 Style of aligning consecutive bit field. 282 283 ``Consecutive`` will align the bitfield separators of consecutive lines. 284 This will result in formattings like: 285 286 .. code-block:: c++ 287 288 int aaaa : 1; 289 int b : 12; 290 int ccc : 8; 291 292 Possible values: 293 294 * ``ACS_None`` (in configuration: ``None``) 295 Do not align bit fields on consecutive lines. 296 297 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 298 Align bit fields on consecutive lines. This will result in 299 formattings like: 300 301 .. code-block:: c++ 302 303 int aaaa : 1; 304 int b : 12; 305 int ccc : 8; 306 307 int d : 2; 308 /* A comment. */ 309 int ee : 3; 310 311 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 312 Same as ACS_Consecutive, but also spans over empty lines, e.g. 313 314 .. code-block:: c++ 315 316 int aaaa : 1; 317 int b : 12; 318 int ccc : 8; 319 320 int d : 2; 321 /* A comment. */ 322 int ee : 3; 323 324 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 325 Same as ACS_Consecutive, but also spans over lines only containing 326 comments, e.g. 327 328 .. code-block:: c++ 329 330 int aaaa : 1; 331 int b : 12; 332 int ccc : 8; 333 334 int d : 2; 335 /* A comment. */ 336 int ee : 3; 337 338 * ``ACS_AcrossEmptyLinesAndComments`` 339 (in configuration: ``AcrossEmptyLinesAndComments``) 340 341 Same as ACS_Consecutive, but also spans over lines only containing 342 comments and empty lines, e.g. 343 344 .. code-block:: c++ 345 346 int aaaa : 1; 347 int b : 12; 348 int ccc : 8; 349 350 int d : 2; 351 /* A comment. */ 352 int ee : 3; 353 354**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) 355 Style of aligning consecutive declarations. 356 357 ``Consecutive`` will align the declaration names of consecutive lines. 358 This will result in formattings like: 359 360 .. code-block:: c++ 361 362 int aaaa = 12; 363 float b = 23; 364 std::string ccc; 365 366 Possible values: 367 368 * ``ACS_None`` (in configuration: ``None``) 369 Do not align bit declarations on consecutive lines. 370 371 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 372 Align declarations on consecutive lines. This will result in 373 formattings like: 374 375 .. code-block:: c++ 376 377 int aaaa = 12; 378 float b = 23; 379 std::string ccc; 380 381 int a = 42; 382 /* A comment. */ 383 bool c = false; 384 385 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 386 Same as ACS_Consecutive, but also spans over empty lines, e.g. 387 388 .. code-block:: c++ 389 390 int aaaa = 12; 391 float b = 23; 392 std::string ccc; 393 394 int a = 42; 395 /* A comment. */ 396 bool c = false; 397 398 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 399 Same as ACS_Consecutive, but also spans over lines only containing 400 comments, e.g. 401 402 .. code-block:: c++ 403 404 int aaaa = 12; 405 float b = 23; 406 std::string ccc; 407 408 int a = 42; 409 /* A comment. */ 410 bool c = false; 411 412 * ``ACS_AcrossEmptyLinesAndComments`` 413 (in configuration: ``AcrossEmptyLinesAndComments``) 414 415 Same as ACS_Consecutive, but also spans over lines only containing 416 comments and empty lines, e.g. 417 418 .. code-block:: c++ 419 420 int aaaa = 12; 421 float b = 23; 422 std::string ccc; 423 424 int a = 42; 425 /* A comment. */ 426 bool c = false; 427 428**AlignConsecutiveMacros** (``AlignConsecutiveStyle``) 429 Style of aligning consecutive macro definitions. 430 431 ``Consecutive`` will result in formattings like: 432 433 .. code-block:: c++ 434 435 #define SHORT_NAME 42 436 #define LONGER_NAME 0x007f 437 #define EVEN_LONGER_NAME (2) 438 #define foo(x) (x * x) 439 #define bar(y, z) (y + z) 440 441 Possible values: 442 443 * ``ACS_None`` (in configuration: ``None``) 444 Do not align macro definitions on consecutive lines. 445 446 * ``ACS_Consecutive`` (in configuration: ``Consecutive``) 447 Align macro definitions on consecutive lines. This will result in 448 formattings like: 449 450 .. code-block:: c++ 451 452 #define SHORT_NAME 42 453 #define LONGER_NAME 0x007f 454 #define EVEN_LONGER_NAME (2) 455 456 #define foo(x) (x * x) 457 /* some comment */ 458 #define bar(y, z) (y + z) 459 460 * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) 461 Same as ACS_Consecutive, but also spans over empty lines, e.g. 462 463 .. code-block:: c++ 464 465 #define SHORT_NAME 42 466 #define LONGER_NAME 0x007f 467 #define EVEN_LONGER_NAME (2) 468 469 #define foo(x) (x * x) 470 /* some comment */ 471 #define bar(y, z) (y + z) 472 473 * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) 474 Same as ACS_Consecutive, but also spans over lines only containing 475 comments, e.g. 476 477 .. code-block:: c++ 478 479 #define SHORT_NAME 42 480 #define LONGER_NAME 0x007f 481 #define EVEN_LONGER_NAME (2) 482 483 #define foo(x) (x * x) 484 /* some comment */ 485 #define bar(y, z) (y + z) 486 487 * ``ACS_AcrossEmptyLinesAndComments`` 488 (in configuration: ``AcrossEmptyLinesAndComments``) 489 490 Same as ACS_Consecutive, but also spans over lines only containing 491 comments and empty lines, e.g. 492 493 .. code-block:: c++ 494 495 #define SHORT_NAME 42 496 #define LONGER_NAME 0x007f 497 #define EVEN_LONGER_NAME (2) 498 499 #define foo(x) (x * x) 500 /* some comment */ 501 #define bar(y, z) (y + z) 502 503**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) 504 Options for aligning backslashes in escaped newlines. 505 506 Possible values: 507 508 * ``ENAS_DontAlign`` (in configuration: ``DontAlign``) 509 Don't align escaped newlines. 510 511 .. code-block:: c++ 512 513 #define A \ 514 int aaaa; \ 515 int b; \ 516 int dddddddddd; 517 518 * ``ENAS_Left`` (in configuration: ``Left``) 519 Align escaped newlines as far left as possible. 520 521 .. code-block:: c++ 522 523 true: 524 #define A \ 525 int aaaa; \ 526 int b; \ 527 int dddddddddd; 528 529 false: 530 531 * ``ENAS_Right`` (in configuration: ``Right``) 532 Align escaped newlines in the right-most column. 533 534 .. code-block:: c++ 535 536 #define A \ 537 int aaaa; \ 538 int b; \ 539 int dddddddddd; 540 541 542 543**AlignOperands** (``OperandAlignmentStyle``) 544 If ``true``, horizontally align operands of binary and ternary 545 expressions. 546 547 Possible values: 548 549 * ``OAS_DontAlign`` (in configuration: ``DontAlign``) 550 Do not align operands of binary and ternary expressions. 551 The wrapped lines are indented ``ContinuationIndentWidth`` spaces from 552 the start of the line. 553 554 * ``OAS_Align`` (in configuration: ``Align``) 555 Horizontally align operands of binary and ternary expressions. 556 557 Specifically, this aligns operands of a single expression that needs 558 to be split over multiple lines, e.g.: 559 560 .. code-block:: c++ 561 562 int aaa = bbbbbbbbbbbbbbb + 563 ccccccccccccccc; 564 565 When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is 566 aligned with the operand on the first line. 567 568 .. code-block:: c++ 569 570 int aaa = bbbbbbbbbbbbbbb 571 + ccccccccccccccc; 572 573 * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``) 574 Horizontally align operands of binary and ternary expressions. 575 576 This is similar to ``AO_Align``, except when 577 ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so 578 that the wrapped operand is aligned with the operand on the first line. 579 580 .. code-block:: c++ 581 582 int aaa = bbbbbbbbbbbbbbb 583 + ccccccccccccccc; 584 585 586 587**AlignTrailingComments** (``bool``) 588 If ``true``, aligns trailing comments. 589 590 .. code-block:: c++ 591 592 true: false: 593 int a; // My comment a vs. int a; // My comment a 594 int b = 2; // comment b int b = 2; // comment about b 595 596**AllowAllArgumentsOnNextLine** (``bool``) 597 If a function call or braced initializer list doesn't fit on a 598 line, allow putting all arguments onto the next line, even if 599 ``BinPackArguments`` is ``false``. 600 601 .. code-block:: c++ 602 603 true: 604 callFunction( 605 a, b, c, d); 606 607 false: 608 callFunction(a, 609 b, 610 c, 611 d); 612 613**AllowAllConstructorInitializersOnNextLine** (``bool``) 614 If a constructor definition with a member initializer list doesn't 615 fit on a single line, allow putting all member initializers onto the next 616 line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true. 617 Note that this parameter has no effect if 618 ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false. 619 620 .. code-block:: c++ 621 622 true: 623 MyClass::MyClass() : 624 member0(0), member1(2) {} 625 626 false: 627 MyClass::MyClass() : 628 member0(0), 629 member1(2) {} 630 631**AllowAllParametersOfDeclarationOnNextLine** (``bool``) 632 If the function declaration doesn't fit on a line, 633 allow putting all parameters of a function declaration onto 634 the next line even if ``BinPackParameters`` is ``false``. 635 636 .. code-block:: c++ 637 638 true: 639 void myFunction( 640 int a, int b, int c, int d, int e); 641 642 false: 643 void myFunction(int a, 644 int b, 645 int c, 646 int d, 647 int e); 648 649**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) 650 Dependent on the value, ``while (true) { continue; }`` can be put on a 651 single line. 652 653 Possible values: 654 655 * ``SBS_Never`` (in configuration: ``Never``) 656 Never merge blocks into a single line. 657 658 .. code-block:: c++ 659 660 while (true) { 661 } 662 while (true) { 663 continue; 664 } 665 666 * ``SBS_Empty`` (in configuration: ``Empty``) 667 Only merge empty blocks. 668 669 .. code-block:: c++ 670 671 while (true) {} 672 while (true) { 673 continue; 674 } 675 676 * ``SBS_Always`` (in configuration: ``Always``) 677 Always merge short blocks into a single line. 678 679 .. code-block:: c++ 680 681 while (true) {} 682 while (true) { continue; } 683 684 685 686**AllowShortCaseLabelsOnASingleLine** (``bool``) 687 If ``true``, short case labels will be contracted to a single line. 688 689 .. code-block:: c++ 690 691 true: false: 692 switch (a) { vs. switch (a) { 693 case 1: x = 1; break; case 1: 694 case 2: return; x = 1; 695 } break; 696 case 2: 697 return; 698 } 699 700**AllowShortEnumsOnASingleLine** (``bool``) 701 Allow short enums on a single line. 702 703 .. code-block:: c++ 704 705 true: 706 enum { A, B } myEnum; 707 708 false: 709 enum 710 { 711 A, 712 B 713 } myEnum; 714 715**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) 716 Dependent on the value, ``int f() { return 0; }`` can be put on a 717 single line. 718 719 Possible values: 720 721 * ``SFS_None`` (in configuration: ``None``) 722 Never merge functions into a single line. 723 724 * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) 725 Only merge functions defined inside a class. Same as "inline", 726 except it does not implies "empty": i.e. top level empty functions 727 are not merged either. 728 729 .. code-block:: c++ 730 731 class Foo { 732 void f() { foo(); } 733 }; 734 void f() { 735 foo(); 736 } 737 void f() { 738 } 739 740 * ``SFS_Empty`` (in configuration: ``Empty``) 741 Only merge empty functions. 742 743 .. code-block:: c++ 744 745 void f() {} 746 void f2() { 747 bar2(); 748 } 749 750 * ``SFS_Inline`` (in configuration: ``Inline``) 751 Only merge functions defined inside a class. Implies "empty". 752 753 .. code-block:: c++ 754 755 class Foo { 756 void f() { foo(); } 757 }; 758 void f() { 759 foo(); 760 } 761 void f() {} 762 763 * ``SFS_All`` (in configuration: ``All``) 764 Merge all functions fitting on a single line. 765 766 .. code-block:: c++ 767 768 class Foo { 769 void f() { foo(); } 770 }; 771 void f() { bar(); } 772 773 774 775**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) 776 If ``true``, ``if (a) return;`` can be put on a single line. 777 778 Possible values: 779 780 * ``SIS_Never`` (in configuration: ``Never``) 781 Never put short ifs on the same line. 782 783 .. code-block:: c++ 784 785 if (a) 786 return ; 787 else { 788 return; 789 } 790 791 * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``) 792 Without else put short ifs on the same line only if 793 the else is not a compound statement. 794 795 .. code-block:: c++ 796 797 if (a) return; 798 else 799 return; 800 801 * ``SIS_Always`` (in configuration: ``Always``) 802 Always put short ifs on the same line if 803 the else is not a compound statement or not. 804 805 .. code-block:: c++ 806 807 if (a) return; 808 else { 809 return; 810 } 811 812 813 814**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) 815 Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a 816 single line. 817 818 Possible values: 819 820 * ``SLS_None`` (in configuration: ``None``) 821 Never merge lambdas into a single line. 822 823 * ``SLS_Empty`` (in configuration: ``Empty``) 824 Only merge empty lambdas. 825 826 .. code-block:: c++ 827 828 auto lambda = [](int a) {} 829 auto lambda2 = [](int a) { 830 return a; 831 }; 832 833 * ``SLS_Inline`` (in configuration: ``Inline``) 834 Merge lambda into a single line if argument of a function. 835 836 .. code-block:: c++ 837 838 auto lambda = [](int a) { 839 return a; 840 }; 841 sort(a.begin(), a.end(), ()[] { return x < y; }) 842 843 * ``SLS_All`` (in configuration: ``All``) 844 Merge all lambdas fitting on a single line. 845 846 .. code-block:: c++ 847 848 auto lambda = [](int a) {} 849 auto lambda2 = [](int a) { return a; }; 850 851 852 853**AllowShortLoopsOnASingleLine** (``bool``) 854 If ``true``, ``while (true) continue;`` can be put on a single 855 line. 856 857**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) 858 The function definition return type breaking style to use. This 859 option is **deprecated** and is retained for backwards compatibility. 860 861 Possible values: 862 863 * ``DRTBS_None`` (in configuration: ``None``) 864 Break after return type automatically. 865 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 866 867 * ``DRTBS_All`` (in configuration: ``All``) 868 Always break after the return type. 869 870 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) 871 Always break after the return types of top-level functions. 872 873 874 875**AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``) 876 The function declaration return type breaking style to use. 877 878 Possible values: 879 880 * ``RTBS_None`` (in configuration: ``None``) 881 Break after return type automatically. 882 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 883 884 .. code-block:: c++ 885 886 class A { 887 int f() { return 0; }; 888 }; 889 int f(); 890 int f() { return 1; } 891 892 * ``RTBS_All`` (in configuration: ``All``) 893 Always break after the return type. 894 895 .. code-block:: c++ 896 897 class A { 898 int 899 f() { 900 return 0; 901 }; 902 }; 903 int 904 f(); 905 int 906 f() { 907 return 1; 908 } 909 910 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) 911 Always break after the return types of top-level functions. 912 913 .. code-block:: c++ 914 915 class A { 916 int f() { return 0; }; 917 }; 918 int 919 f(); 920 int 921 f() { 922 return 1; 923 } 924 925 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) 926 Always break after the return type of function definitions. 927 928 .. code-block:: c++ 929 930 class A { 931 int 932 f() { 933 return 0; 934 }; 935 }; 936 int f(); 937 int 938 f() { 939 return 1; 940 } 941 942 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) 943 Always break after the return type of top-level definitions. 944 945 .. code-block:: c++ 946 947 class A { 948 int f() { return 0; }; 949 }; 950 int f(); 951 int 952 f() { 953 return 1; 954 } 955 956 957 958**AlwaysBreakBeforeMultilineStrings** (``bool``) 959 If ``true``, always break before multiline string literals. 960 961 This flag is mean to make cases where there are multiple multiline strings 962 in a file look more consistent. Thus, it will only take effect if wrapping 963 the string at that point leads to it being indented 964 ``ContinuationIndentWidth`` spaces from the start of the line. 965 966 .. code-block:: c++ 967 968 true: false: 969 aaaa = vs. aaaa = "bbbb" 970 "bbbb" "cccc"; 971 "cccc"; 972 973**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) 974 The template declaration breaking style to use. 975 976 Possible values: 977 978 * ``BTDS_No`` (in configuration: ``No``) 979 Do not force break before declaration. 980 ``PenaltyBreakTemplateDeclaration`` is taken into account. 981 982 .. code-block:: c++ 983 984 template <typename T> T foo() { 985 } 986 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, 987 int bbbbbbbbbbbbbbbbbbbbb) { 988 } 989 990 * ``BTDS_MultiLine`` (in configuration: ``MultiLine``) 991 Force break after template declaration only when the following 992 declaration spans multiple lines. 993 994 .. code-block:: c++ 995 996 template <typename T> T foo() { 997 } 998 template <typename T> 999 T foo(int aaaaaaaaaaaaaaaaaaaaa, 1000 int bbbbbbbbbbbbbbbbbbbbb) { 1001 } 1002 1003 * ``BTDS_Yes`` (in configuration: ``Yes``) 1004 Always break after template declaration. 1005 1006 .. code-block:: c++ 1007 1008 template <typename T> 1009 T foo() { 1010 } 1011 template <typename T> 1012 T foo(int aaaaaaaaaaaaaaaaaaaaa, 1013 int bbbbbbbbbbbbbbbbbbbbb) { 1014 } 1015 1016 1017 1018**AttributeMacros** (``std::vector<std::string>``) 1019 A vector of strings that should be interpreted as attributes/qualifiers 1020 instead of identifiers. This can be useful for language extensions or 1021 static analyzer annotations. 1022 1023 For example: 1024 1025 .. code-block:: c++ 1026 1027 x = (char *__capability)&y; 1028 int function(void) __ununsed; 1029 void only_writes_to_buffer(char *__output buffer); 1030 1031 In the .clang-format configuration file, this can be configured like: 1032 1033 .. code-block:: yaml 1034 1035 AttributeMacros: ['__capability', '__output', '__ununsed'] 1036 1037**BinPackArguments** (``bool``) 1038 If ``false``, a function call's arguments will either be all on the 1039 same line or will have one line each. 1040 1041 .. code-block:: c++ 1042 1043 true: 1044 void f() { 1045 f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, 1046 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 1047 } 1048 1049 false: 1050 void f() { 1051 f(aaaaaaaaaaaaaaaaaaaa, 1052 aaaaaaaaaaaaaaaaaaaa, 1053 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 1054 } 1055 1056**BinPackParameters** (``bool``) 1057 If ``false``, a function declaration's or function definition's 1058 parameters will either all be on the same line or will have one line each. 1059 1060 .. code-block:: c++ 1061 1062 true: 1063 void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa, 1064 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 1065 1066 false: 1067 void f(int aaaaaaaaaaaaaaaaaaaa, 1068 int aaaaaaaaaaaaaaaaaaaa, 1069 int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} 1070 1071**BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) 1072 The BitFieldColonSpacingStyle to use for bitfields. 1073 1074 Possible values: 1075 1076 * ``BFCS_Both`` (in configuration: ``Both``) 1077 Add one space on each side of the ``:`` 1078 1079 .. code-block:: c++ 1080 1081 unsigned bf : 2; 1082 1083 * ``BFCS_None`` (in configuration: ``None``) 1084 Add no space around the ``:`` (except when needed for 1085 ``AlignConsecutiveBitFields``). 1086 1087 .. code-block:: c++ 1088 1089 unsigned bf:2; 1090 1091 * ``BFCS_Before`` (in configuration: ``Before``) 1092 Add space before the ``:`` only 1093 1094 .. code-block:: c++ 1095 1096 unsigned bf :2; 1097 1098 * ``BFCS_After`` (in configuration: ``After``) 1099 Add space after the ``:`` only (space may be added before if 1100 needed for ``AlignConsecutiveBitFields``). 1101 1102 .. code-block:: c++ 1103 1104 unsigned bf: 2; 1105 1106 1107 1108**BraceWrapping** (``BraceWrappingFlags``) 1109 Control of individual brace wrapping cases. 1110 1111 If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how 1112 each individual brace case should be handled. Otherwise, this is ignored. 1113 1114 .. code-block:: yaml 1115 1116 # Example of usage: 1117 BreakBeforeBraces: Custom 1118 BraceWrapping: 1119 AfterEnum: true 1120 AfterStruct: false 1121 SplitEmptyFunction: false 1122 1123 Nested configuration flags: 1124 1125 1126 * ``bool AfterCaseLabel`` Wrap case labels. 1127 1128 .. code-block:: c++ 1129 1130 false: true: 1131 switch (foo) { vs. switch (foo) { 1132 case 1: { case 1: 1133 bar(); { 1134 break; bar(); 1135 } break; 1136 default: { } 1137 plop(); default: 1138 } { 1139 } plop(); 1140 } 1141 } 1142 1143 * ``bool AfterClass`` Wrap class definitions. 1144 1145 .. code-block:: c++ 1146 1147 true: 1148 class foo {}; 1149 1150 false: 1151 class foo 1152 {}; 1153 1154 * ``BraceWrappingAfterControlStatementStyle AfterControlStatement`` 1155 Wrap control statements (``if``/``for``/``while``/``switch``/..). 1156 1157 Possible values: 1158 1159 * ``BWACS_Never`` (in configuration: ``Never``) 1160 Never wrap braces after a control statement. 1161 1162 .. code-block:: c++ 1163 1164 if (foo()) { 1165 } else { 1166 } 1167 for (int i = 0; i < 10; ++i) { 1168 } 1169 1170 * ``BWACS_MultiLine`` (in configuration: ``MultiLine``) 1171 Only wrap braces after a multi-line control statement. 1172 1173 .. code-block:: c++ 1174 1175 if (foo && bar && 1176 baz) 1177 { 1178 quux(); 1179 } 1180 while (foo || bar) { 1181 } 1182 1183 * ``BWACS_Always`` (in configuration: ``Always``) 1184 Always wrap braces after a control statement. 1185 1186 .. code-block:: c++ 1187 1188 if (foo()) 1189 { 1190 } else 1191 {} 1192 for (int i = 0; i < 10; ++i) 1193 {} 1194 1195 1196 * ``bool AfterEnum`` Wrap enum definitions. 1197 1198 .. code-block:: c++ 1199 1200 true: 1201 enum X : int 1202 { 1203 B 1204 }; 1205 1206 false: 1207 enum X : int { B }; 1208 1209 * ``bool AfterFunction`` Wrap function definitions. 1210 1211 .. code-block:: c++ 1212 1213 true: 1214 void foo() 1215 { 1216 bar(); 1217 bar2(); 1218 } 1219 1220 false: 1221 void foo() { 1222 bar(); 1223 bar2(); 1224 } 1225 1226 * ``bool AfterNamespace`` Wrap namespace definitions. 1227 1228 .. code-block:: c++ 1229 1230 true: 1231 namespace 1232 { 1233 int foo(); 1234 int bar(); 1235 } 1236 1237 false: 1238 namespace { 1239 int foo(); 1240 int bar(); 1241 } 1242 1243 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). 1244 @autoreleasepool and @synchronized blocks are wrapped 1245 according to `AfterControlStatement` flag. 1246 1247 * ``bool AfterStruct`` Wrap struct definitions. 1248 1249 .. code-block:: c++ 1250 1251 true: 1252 struct foo 1253 { 1254 int x; 1255 }; 1256 1257 false: 1258 struct foo { 1259 int x; 1260 }; 1261 1262 * ``bool AfterUnion`` Wrap union definitions. 1263 1264 .. code-block:: c++ 1265 1266 true: 1267 union foo 1268 { 1269 int x; 1270 } 1271 1272 false: 1273 union foo { 1274 int x; 1275 } 1276 1277 * ``bool AfterExternBlock`` Wrap extern blocks. 1278 1279 .. code-block:: c++ 1280 1281 true: 1282 extern "C" 1283 { 1284 int foo(); 1285 } 1286 1287 false: 1288 extern "C" { 1289 int foo(); 1290 } 1291 1292 * ``bool BeforeCatch`` Wrap before ``catch``. 1293 1294 .. code-block:: c++ 1295 1296 true: 1297 try { 1298 foo(); 1299 } 1300 catch () { 1301 } 1302 1303 false: 1304 try { 1305 foo(); 1306 } catch () { 1307 } 1308 1309 * ``bool BeforeElse`` Wrap before ``else``. 1310 1311 .. code-block:: c++ 1312 1313 true: 1314 if (foo()) { 1315 } 1316 else { 1317 } 1318 1319 false: 1320 if (foo()) { 1321 } else { 1322 } 1323 1324 * ``bool BeforeLambdaBody`` Wrap lambda block. 1325 1326 .. code-block:: c++ 1327 1328 true: 1329 connect( 1330 []() 1331 { 1332 foo(); 1333 bar(); 1334 }); 1335 1336 false: 1337 connect([]() { 1338 foo(); 1339 bar(); 1340 }); 1341 1342 * ``bool BeforeWhile`` Wrap before ``while``. 1343 1344 .. code-block:: c++ 1345 1346 true: 1347 do { 1348 foo(); 1349 } 1350 while (1); 1351 1352 false: 1353 do { 1354 foo(); 1355 } while (1); 1356 1357 * ``bool IndentBraces`` Indent the wrapped braces themselves. 1358 1359 * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line. 1360 This option is used only if the opening brace of the function has 1361 already been wrapped, i.e. the `AfterFunction` brace wrapping mode is 1362 set, and the function could/should not be put on a single line (as per 1363 `AllowShortFunctionsOnASingleLine` and constructor formatting options). 1364 1365 .. code-block:: c++ 1366 1367 int f() vs. int f() 1368 {} { 1369 } 1370 1371 * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body 1372 can be put on a single line. This option is used only if the opening 1373 brace of the record has already been wrapped, i.e. the `AfterClass` 1374 (for classes) brace wrapping mode is set. 1375 1376 .. code-block:: c++ 1377 1378 class Foo vs. class Foo 1379 {} { 1380 } 1381 1382 * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line. 1383 This option is used only if the opening brace of the namespace has 1384 already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is 1385 set. 1386 1387 .. code-block:: c++ 1388 1389 namespace Foo vs. namespace Foo 1390 {} { 1391 } 1392 1393 1394**BreakAfterJavaFieldAnnotations** (``bool``) 1395 Break after each annotation on a field in Java files. 1396 1397 .. code-block:: java 1398 1399 true: false: 1400 @Partial vs. @Partial @Mock DataLoad loader; 1401 @Mock 1402 DataLoad loader; 1403 1404**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) 1405 The way to wrap binary operators. 1406 1407 Possible values: 1408 1409 * ``BOS_None`` (in configuration: ``None``) 1410 Break after operators. 1411 1412 .. code-block:: c++ 1413 1414 LooooooooooongType loooooooooooooooooooooongVariable = 1415 someLooooooooooooooooongFunction(); 1416 1417 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + 1418 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == 1419 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && 1420 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > 1421 ccccccccccccccccccccccccccccccccccccccccc; 1422 1423 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) 1424 Break before operators that aren't assignments. 1425 1426 .. code-block:: c++ 1427 1428 LooooooooooongType loooooooooooooooooooooongVariable = 1429 someLooooooooooooooooongFunction(); 1430 1431 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1432 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1433 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1434 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1435 > ccccccccccccccccccccccccccccccccccccccccc; 1436 1437 * ``BOS_All`` (in configuration: ``All``) 1438 Break before operators. 1439 1440 .. code-block:: c++ 1441 1442 LooooooooooongType loooooooooooooooooooooongVariable 1443 = someLooooooooooooooooongFunction(); 1444 1445 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1446 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1447 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1448 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 1449 > ccccccccccccccccccccccccccccccccccccccccc; 1450 1451 1452 1453**BreakBeforeBraces** (``BraceBreakingStyle``) 1454 The brace breaking style to use. 1455 1456 Possible values: 1457 1458 * ``BS_Attach`` (in configuration: ``Attach``) 1459 Always attach braces to surrounding context. 1460 1461 .. code-block:: c++ 1462 1463 namespace N { 1464 enum E { 1465 E1, 1466 E2, 1467 }; 1468 1469 class C { 1470 public: 1471 C(); 1472 }; 1473 1474 bool baz(int i) { 1475 try { 1476 do { 1477 switch (i) { 1478 case 1: { 1479 foobar(); 1480 break; 1481 } 1482 default: { 1483 break; 1484 } 1485 } 1486 } while (--i); 1487 return true; 1488 } catch (...) { 1489 handleError(); 1490 return false; 1491 } 1492 } 1493 1494 void foo(bool b) { 1495 if (b) { 1496 baz(2); 1497 } else { 1498 baz(5); 1499 } 1500 } 1501 1502 void bar() { foo(true); } 1503 } // namespace N 1504 1505 * ``BS_Linux`` (in configuration: ``Linux``) 1506 Like ``Attach``, but break before braces on function, namespace and 1507 class definitions. 1508 1509 .. code-block:: c++ 1510 1511 namespace N 1512 { 1513 enum E { 1514 E1, 1515 E2, 1516 }; 1517 1518 class C 1519 { 1520 public: 1521 C(); 1522 }; 1523 1524 bool baz(int i) 1525 { 1526 try { 1527 do { 1528 switch (i) { 1529 case 1: { 1530 foobar(); 1531 break; 1532 } 1533 default: { 1534 break; 1535 } 1536 } 1537 } while (--i); 1538 return true; 1539 } catch (...) { 1540 handleError(); 1541 return false; 1542 } 1543 } 1544 1545 void foo(bool b) 1546 { 1547 if (b) { 1548 baz(2); 1549 } else { 1550 baz(5); 1551 } 1552 } 1553 1554 void bar() { foo(true); } 1555 } // namespace N 1556 1557 * ``BS_Mozilla`` (in configuration: ``Mozilla``) 1558 Like ``Attach``, but break before braces on enum, function, and record 1559 definitions. 1560 1561 .. code-block:: c++ 1562 1563 namespace N { 1564 enum E 1565 { 1566 E1, 1567 E2, 1568 }; 1569 1570 class C 1571 { 1572 public: 1573 C(); 1574 }; 1575 1576 bool baz(int i) 1577 { 1578 try { 1579 do { 1580 switch (i) { 1581 case 1: { 1582 foobar(); 1583 break; 1584 } 1585 default: { 1586 break; 1587 } 1588 } 1589 } while (--i); 1590 return true; 1591 } catch (...) { 1592 handleError(); 1593 return false; 1594 } 1595 } 1596 1597 void foo(bool b) 1598 { 1599 if (b) { 1600 baz(2); 1601 } else { 1602 baz(5); 1603 } 1604 } 1605 1606 void bar() { foo(true); } 1607 } // namespace N 1608 1609 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) 1610 Like ``Attach``, but break before function definitions, ``catch``, and 1611 ``else``. 1612 1613 .. code-block:: c++ 1614 1615 namespace N { 1616 enum E { 1617 E1, 1618 E2, 1619 }; 1620 1621 class C { 1622 public: 1623 C(); 1624 }; 1625 1626 bool baz(int i) 1627 { 1628 try { 1629 do { 1630 switch (i) { 1631 case 1: { 1632 foobar(); 1633 break; 1634 } 1635 default: { 1636 break; 1637 } 1638 } 1639 } while (--i); 1640 return true; 1641 } 1642 catch (...) { 1643 handleError(); 1644 return false; 1645 } 1646 } 1647 1648 void foo(bool b) 1649 { 1650 if (b) { 1651 baz(2); 1652 } 1653 else { 1654 baz(5); 1655 } 1656 } 1657 1658 void bar() { foo(true); } 1659 } // namespace N 1660 1661 * ``BS_Allman`` (in configuration: ``Allman``) 1662 Always break before braces. 1663 1664 .. code-block:: c++ 1665 1666 namespace N 1667 { 1668 enum E 1669 { 1670 E1, 1671 E2, 1672 }; 1673 1674 class C 1675 { 1676 public: 1677 C(); 1678 }; 1679 1680 bool baz(int i) 1681 { 1682 try 1683 { 1684 do 1685 { 1686 switch (i) 1687 { 1688 case 1: 1689 { 1690 foobar(); 1691 break; 1692 } 1693 default: 1694 { 1695 break; 1696 } 1697 } 1698 } while (--i); 1699 return true; 1700 } 1701 catch (...) 1702 { 1703 handleError(); 1704 return false; 1705 } 1706 } 1707 1708 void foo(bool b) 1709 { 1710 if (b) 1711 { 1712 baz(2); 1713 } 1714 else 1715 { 1716 baz(5); 1717 } 1718 } 1719 1720 void bar() { foo(true); } 1721 } // namespace N 1722 1723 * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``) 1724 Like ``Allman`` but always indent braces and line up code with braces. 1725 1726 .. code-block:: c++ 1727 1728 namespace N 1729 { 1730 enum E 1731 { 1732 E1, 1733 E2, 1734 }; 1735 1736 class C 1737 { 1738 public: 1739 C(); 1740 }; 1741 1742 bool baz(int i) 1743 { 1744 try 1745 { 1746 do 1747 { 1748 switch (i) 1749 { 1750 case 1: 1751 { 1752 foobar(); 1753 break; 1754 } 1755 default: 1756 { 1757 break; 1758 } 1759 } 1760 } while (--i); 1761 return true; 1762 } 1763 catch (...) 1764 { 1765 handleError(); 1766 return false; 1767 } 1768 } 1769 1770 void foo(bool b) 1771 { 1772 if (b) 1773 { 1774 baz(2); 1775 } 1776 else 1777 { 1778 baz(5); 1779 } 1780 } 1781 1782 void bar() { foo(true); } 1783 } // namespace N 1784 1785 * ``BS_GNU`` (in configuration: ``GNU``) 1786 Always break before braces and add an extra level of indentation to 1787 braces of control statements, not to those of class, function 1788 or other definitions. 1789 1790 .. code-block:: c++ 1791 1792 namespace N 1793 { 1794 enum E 1795 { 1796 E1, 1797 E2, 1798 }; 1799 1800 class C 1801 { 1802 public: 1803 C(); 1804 }; 1805 1806 bool baz(int i) 1807 { 1808 try 1809 { 1810 do 1811 { 1812 switch (i) 1813 { 1814 case 1: 1815 { 1816 foobar(); 1817 break; 1818 } 1819 default: 1820 { 1821 break; 1822 } 1823 } 1824 } 1825 while (--i); 1826 return true; 1827 } 1828 catch (...) 1829 { 1830 handleError(); 1831 return false; 1832 } 1833 } 1834 1835 void foo(bool b) 1836 { 1837 if (b) 1838 { 1839 baz(2); 1840 } 1841 else 1842 { 1843 baz(5); 1844 } 1845 } 1846 1847 void bar() { foo(true); } 1848 } // namespace N 1849 1850 * ``BS_WebKit`` (in configuration: ``WebKit``) 1851 Like ``Attach``, but break before functions. 1852 1853 .. code-block:: c++ 1854 1855 namespace N { 1856 enum E { 1857 E1, 1858 E2, 1859 }; 1860 1861 class C { 1862 public: 1863 C(); 1864 }; 1865 1866 bool baz(int i) 1867 { 1868 try { 1869 do { 1870 switch (i) { 1871 case 1: { 1872 foobar(); 1873 break; 1874 } 1875 default: { 1876 break; 1877 } 1878 } 1879 } while (--i); 1880 return true; 1881 } catch (...) { 1882 handleError(); 1883 return false; 1884 } 1885 } 1886 1887 void foo(bool b) 1888 { 1889 if (b) { 1890 baz(2); 1891 } else { 1892 baz(5); 1893 } 1894 } 1895 1896 void bar() { foo(true); } 1897 } // namespace N 1898 1899 * ``BS_Custom`` (in configuration: ``Custom``) 1900 Configure each individual brace in `BraceWrapping`. 1901 1902 1903 1904**BreakBeforeConceptDeclarations** (``bool``) 1905 If ``true``, concept will be placed on a new line. 1906 1907 .. code-block:: c++ 1908 1909 true: 1910 template<typename T> 1911 concept ... 1912 1913 false: 1914 template<typename T> concept ... 1915 1916**BreakBeforeTernaryOperators** (``bool``) 1917 If ``true``, ternary operators will be placed after line breaks. 1918 1919 .. code-block:: c++ 1920 1921 true: 1922 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription 1923 ? firstValue 1924 : SecondValueVeryVeryVeryVeryLong; 1925 1926 false: 1927 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? 1928 firstValue : 1929 SecondValueVeryVeryVeryVeryLong; 1930 1931**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) 1932 The constructor initializers style to use. 1933 1934 Possible values: 1935 1936 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) 1937 Break constructor initializers before the colon and after the commas. 1938 1939 .. code-block:: c++ 1940 1941 Constructor() 1942 : initializer1(), 1943 initializer2() 1944 1945 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) 1946 Break constructor initializers before the colon and commas, and align 1947 the commas with the colon. 1948 1949 .. code-block:: c++ 1950 1951 Constructor() 1952 : initializer1() 1953 , initializer2() 1954 1955 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) 1956 Break constructor initializers after the colon and commas. 1957 1958 .. code-block:: c++ 1959 1960 Constructor() : 1961 initializer1(), 1962 initializer2() 1963 1964 1965 1966**BreakInheritanceList** (``BreakInheritanceListStyle``) 1967 The inheritance list style to use. 1968 1969 Possible values: 1970 1971 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) 1972 Break inheritance list before the colon and after the commas. 1973 1974 .. code-block:: c++ 1975 1976 class Foo 1977 : Base1, 1978 Base2 1979 {}; 1980 1981 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) 1982 Break inheritance list before the colon and commas, and align 1983 the commas with the colon. 1984 1985 .. code-block:: c++ 1986 1987 class Foo 1988 : Base1 1989 , Base2 1990 {}; 1991 1992 * ``BILS_AfterColon`` (in configuration: ``AfterColon``) 1993 Break inheritance list after the colon and commas. 1994 1995 .. code-block:: c++ 1996 1997 class Foo : 1998 Base1, 1999 Base2 2000 {}; 2001 2002 2003 2004**BreakStringLiterals** (``bool``) 2005 Allow breaking string literals when formatting. 2006 2007 .. code-block:: c++ 2008 2009 true: 2010 const char* x = "veryVeryVeryVeryVeryVe" 2011 "ryVeryVeryVeryVeryVery" 2012 "VeryLongString"; 2013 2014 false: 2015 const char* x = 2016 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; 2017 2018**ColumnLimit** (``unsigned``) 2019 The column limit. 2020 2021 A column limit of ``0`` means that there is no column limit. In this case, 2022 clang-format will respect the input's line breaking decisions within 2023 statements unless they contradict other rules. 2024 2025**CommentPragmas** (``std::string``) 2026 A regular expression that describes comments with special meaning, 2027 which should not be split into lines or otherwise changed. 2028 2029 .. code-block:: c++ 2030 2031 // CommentPragmas: '^ FOOBAR pragma:' 2032 // Will leave the following line unaffected 2033 #include <vector> // FOOBAR pragma: keep 2034 2035**CompactNamespaces** (``bool``) 2036 If ``true``, consecutive namespace declarations will be on the same 2037 line. If ``false``, each namespace is declared on a new line. 2038 2039 .. code-block:: c++ 2040 2041 true: 2042 namespace Foo { namespace Bar { 2043 }} 2044 2045 false: 2046 namespace Foo { 2047 namespace Bar { 2048 } 2049 } 2050 2051 If it does not fit on a single line, the overflowing namespaces get 2052 wrapped: 2053 2054 .. code-block:: c++ 2055 2056 namespace Foo { namespace Bar { 2057 namespace Extra { 2058 }}} 2059 2060**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) 2061 If the constructor initializers don't fit on a line, put each 2062 initializer on its own line. 2063 2064 .. code-block:: c++ 2065 2066 true: 2067 SomeClass::Constructor() 2068 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 2069 return 0; 2070 } 2071 2072 false: 2073 SomeClass::Constructor() 2074 : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), 2075 aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { 2076 return 0; 2077 } 2078 2079**ConstructorInitializerIndentWidth** (``unsigned``) 2080 The number of characters to use for indentation of constructor 2081 initializer lists as well as inheritance lists. 2082 2083**ContinuationIndentWidth** (``unsigned``) 2084 Indent width for line continuations. 2085 2086 .. code-block:: c++ 2087 2088 ContinuationIndentWidth: 2 2089 2090 int i = // VeryVeryVeryVeryVeryLongComment 2091 longFunction( // Again a long comment 2092 arg); 2093 2094**Cpp11BracedListStyle** (``bool``) 2095 If ``true``, format braced lists as best suited for C++11 braced 2096 lists. 2097 2098 Important differences: 2099 - No spaces inside the braced list. 2100 - No line break before the closing brace. 2101 - Indentation with the continuation indent, not with the block indent. 2102 2103 Fundamentally, C++11 braced lists are formatted exactly like function 2104 calls would be formatted in their place. If the braced list follows a name 2105 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 2106 the parentheses of a function call with that name. If there is no name, 2107 a zero-length name is assumed. 2108 2109 .. code-block:: c++ 2110 2111 true: false: 2112 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 }; 2113 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} }; 2114 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); 2115 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; 2116 2117**DeriveLineEnding** (``bool``) 2118 Analyze the formatted file for the most used line ending (``\r\n`` 2119 or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived. 2120 2121**DerivePointerAlignment** (``bool``) 2122 If ``true``, analyze the formatted file for the most common 2123 alignment of ``&`` and ``*``. 2124 Pointer and reference alignment styles are going to be updated according 2125 to the preferences found in the file. 2126 ``PointerAlignment`` is then used only as fallback. 2127 2128**DisableFormat** (``bool``) 2129 Disables formatting completely. 2130 2131**EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) 2132 Defines when to put an empty line after access modifiers. 2133 ``EmptyLineBeforeAccessModifier`` configuration handles the number of 2134 empty lines between two access modifiers. 2135 2136 Possible values: 2137 2138 * ``ELAAMS_Never`` (in configuration: ``Never``) 2139 Remove all empty lines after access modifiers. 2140 2141 .. code-block:: c++ 2142 2143 struct foo { 2144 private: 2145 int i; 2146 protected: 2147 int j; 2148 /* comment */ 2149 public: 2150 foo() {} 2151 private: 2152 protected: 2153 }; 2154 2155 * ``ELAAMS_Leave`` (in configuration: ``Leave``) 2156 Keep existing empty lines after access modifiers. 2157 MaxEmptyLinesToKeep is applied instead. 2158 2159 * ``ELAAMS_Always`` (in configuration: ``Always``) 2160 Always add empty line after access modifiers if there are none. 2161 MaxEmptyLinesToKeep is applied also. 2162 2163 .. code-block:: c++ 2164 2165 struct foo { 2166 private: 2167 2168 int i; 2169 protected: 2170 2171 int j; 2172 /* comment */ 2173 public: 2174 2175 foo() {} 2176 private: 2177 2178 protected: 2179 }; 2180 2181**EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) 2182 Defines in which cases to put empty line before access modifiers. 2183 2184 Possible values: 2185 2186 * ``ELBAMS_Never`` (in configuration: ``Never``) 2187 Remove all empty lines before access modifiers. 2188 2189 .. code-block:: c++ 2190 2191 struct foo { 2192 private: 2193 int i; 2194 protected: 2195 int j; 2196 /* comment */ 2197 public: 2198 foo() {} 2199 private: 2200 protected: 2201 }; 2202 2203 * ``ELBAMS_Leave`` (in configuration: ``Leave``) 2204 Keep existing empty lines before access modifiers. 2205 2206 * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``) 2207 Add empty line only when access modifier starts a new logical block. 2208 Logical block is a group of one or more member fields or functions. 2209 2210 .. code-block:: c++ 2211 2212 struct foo { 2213 private: 2214 int i; 2215 2216 protected: 2217 int j; 2218 /* comment */ 2219 public: 2220 foo() {} 2221 2222 private: 2223 protected: 2224 }; 2225 2226 * ``ELBAMS_Always`` (in configuration: ``Always``) 2227 Always add empty line before access modifiers unless access modifier 2228 is at the start of struct or class definition. 2229 2230 .. code-block:: c++ 2231 2232 struct foo { 2233 private: 2234 int i; 2235 2236 protected: 2237 int j; 2238 /* comment */ 2239 2240 public: 2241 foo() {} 2242 2243 private: 2244 2245 protected: 2246 }; 2247 2248**ExperimentalAutoDetectBinPacking** (``bool``) 2249 If ``true``, clang-format detects whether function calls and 2250 definitions are formatted with one parameter per line. 2251 2252 Each call can be bin-packed, one-per-line or inconclusive. If it is 2253 inconclusive, e.g. completely on one line, but a decision needs to be 2254 made, clang-format analyzes whether there are other bin-packed cases in 2255 the input file and act accordingly. 2256 2257 NOTE: This is an experimental flag, that might go away or be renamed. Do 2258 not use this in config files, etc. Use at your own risk. 2259 2260**FixNamespaceComments** (``bool``) 2261 If ``true``, clang-format adds missing namespace end comments for 2262 short namespaces and fixes invalid existing ones. Short ones are 2263 controlled by "ShortNamespaceLines". 2264 2265 .. code-block:: c++ 2266 2267 true: false: 2268 namespace a { vs. namespace a { 2269 foo(); foo(); 2270 bar(); bar(); 2271 } // namespace a } 2272 2273**ForEachMacros** (``std::vector<std::string>``) 2274 A vector of macros that should be interpreted as foreach loops 2275 instead of as function calls. 2276 2277 These are expected to be macros of the form: 2278 2279 .. code-block:: c++ 2280 2281 FOREACH(<variable-declaration>, ...) 2282 <loop-body> 2283 2284 In the .clang-format configuration file, this can be configured like: 2285 2286 .. code-block:: yaml 2287 2288 ForEachMacros: ['RANGES_FOR', 'FOREACH'] 2289 2290 For example: BOOST_FOREACH. 2291 2292**IncludeBlocks** (``IncludeBlocksStyle``) 2293 Dependent on the value, multiple ``#include`` blocks can be sorted 2294 as one and divided based on category. 2295 2296 Possible values: 2297 2298 * ``IBS_Preserve`` (in configuration: ``Preserve``) 2299 Sort each ``#include`` block separately. 2300 2301 .. code-block:: c++ 2302 2303 #include "b.h" into #include "b.h" 2304 2305 #include <lib/main.h> #include "a.h" 2306 #include "a.h" #include <lib/main.h> 2307 2308 * ``IBS_Merge`` (in configuration: ``Merge``) 2309 Merge multiple ``#include`` blocks together and sort as one. 2310 2311 .. code-block:: c++ 2312 2313 #include "b.h" into #include "a.h" 2314 #include "b.h" 2315 #include <lib/main.h> #include <lib/main.h> 2316 #include "a.h" 2317 2318 * ``IBS_Regroup`` (in configuration: ``Regroup``) 2319 Merge multiple ``#include`` blocks together and sort as one. 2320 Then split into groups based on category priority. See 2321 ``IncludeCategories``. 2322 2323 .. code-block:: c++ 2324 2325 #include "b.h" into #include "a.h" 2326 #include "b.h" 2327 #include <lib/main.h> 2328 #include "a.h" #include <lib/main.h> 2329 2330 2331 2332**IncludeCategories** (``std::vector<IncludeCategory>``) 2333 Regular expressions denoting the different ``#include`` categories 2334 used for ordering ``#includes``. 2335 2336 `POSIX extended 2337 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ 2338 regular expressions are supported. 2339 2340 These regular expressions are matched against the filename of an include 2341 (including the <> or "") in order. The value belonging to the first 2342 matching regular expression is assigned and ``#includes`` are sorted first 2343 according to increasing category number and then alphabetically within 2344 each category. 2345 2346 If none of the regular expressions match, INT_MAX is assigned as 2347 category. The main header for a source file automatically gets category 0. 2348 so that it is generally kept at the beginning of the ``#includes`` 2349 (https://llvm.org/docs/CodingStandards.html#include-style). However, you 2350 can also assign negative priorities if you have certain headers that 2351 always need to be first. 2352 2353 There is a third and optional field ``SortPriority`` which can used while 2354 ``IncludeBlocks = IBS_Regroup`` to define the priority in which 2355 ``#includes`` should be ordered. The value of ``Priority`` defines the 2356 order of ``#include blocks`` and also allows the grouping of ``#includes`` 2357 of different priority. ``SortPriority`` is set to the value of 2358 ``Priority`` as default if it is not assigned. 2359 2360 Each regular expression can be marked as case sensitive with the field 2361 ``CaseSensitive``, per default it is not. 2362 2363 To configure this in the .clang-format file, use: 2364 2365 .. code-block:: yaml 2366 2367 IncludeCategories: 2368 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 2369 Priority: 2 2370 SortPriority: 2 2371 CaseSensitive: true 2372 - Regex: '^(<|"(gtest|gmock|isl|json)/)' 2373 Priority: 3 2374 - Regex: '<[[:alnum:].]+>' 2375 Priority: 4 2376 - Regex: '.*' 2377 Priority: 1 2378 SortPriority: 0 2379 2380**IncludeIsMainRegex** (``std::string``) 2381 Specify a regular expression of suffixes that are allowed in the 2382 file-to-main-include mapping. 2383 2384 When guessing whether a #include is the "main" include (to assign 2385 category 0, see above), use this regex of allowed suffixes to the header 2386 stem. A partial match is done, so that: 2387 - "" means "arbitrary suffix" 2388 - "$" means "no suffix" 2389 2390 For example, if configured to "(_test)?$", then a header a.h would be seen 2391 as the "main" include in both a.cc and a_test.cc. 2392 2393**IncludeIsMainSourceRegex** (``std::string``) 2394 Specify a regular expression for files being formatted 2395 that are allowed to be considered "main" in the 2396 file-to-main-include mapping. 2397 2398 By default, clang-format considers files as "main" only when they end 2399 with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm`` 2400 extensions. 2401 For these files a guessing of "main" include takes place 2402 (to assign category 0, see above). This config option allows for 2403 additional suffixes and extensions for files to be considered as "main". 2404 2405 For example, if this option is configured to ``(Impl\.hpp)$``, 2406 then a file ``ClassImpl.hpp`` is considered "main" (in addition to 2407 ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main 2408 include file" logic will be executed (with *IncludeIsMainRegex* setting 2409 also being respected in later phase). Without this option set, 2410 ``ClassImpl.hpp`` would not have the main include file put on top 2411 before any other include. 2412 2413**IndentAccessModifiers** (``bool``) 2414 Specify whether access modifiers should have their own indentation level. 2415 2416 When ``false``, access modifiers are indented (or outdented) relative to 2417 the record members, respecting the ``AccessModifierOffset``. Record 2418 members are indented one level below the record. 2419 When ``true``, access modifiers get their own indentation level. As a 2420 consequence, record members are always indented 2 levels below the record, 2421 regardless of the access modifier presence. Value of the 2422 ``AccessModifierOffset`` is ignored. 2423 2424 .. code-block:: c++ 2425 2426 false: true: 2427 class C { vs. class C { 2428 class D { class D { 2429 void bar(); void bar(); 2430 protected: protected: 2431 D(); D(); 2432 }; }; 2433 public: public: 2434 C(); C(); 2435 }; }; 2436 void foo() { void foo() { 2437 return 1; return 1; 2438 } } 2439 2440**IndentCaseBlocks** (``bool``) 2441 Indent case label blocks one level from the case label. 2442 2443 When ``false``, the block following the case label uses the same 2444 indentation level as for the case label, treating the case label the same 2445 as an if-statement. 2446 When ``true``, the block gets indented as a scope block. 2447 2448 .. code-block:: c++ 2449 2450 false: true: 2451 switch (fool) { vs. switch (fool) { 2452 case 1: { case 1: 2453 bar(); { 2454 } break; bar(); 2455 default: { } 2456 plop(); break; 2457 } default: 2458 } { 2459 plop(); 2460 } 2461 } 2462 2463**IndentCaseLabels** (``bool``) 2464 Indent case labels one level from the switch statement. 2465 2466 When ``false``, use the same indentation level as for the switch 2467 statement. Switch statement body is always indented one level more than 2468 case labels (except the first block following the case label, which 2469 itself indents the code - unless IndentCaseBlocks is enabled). 2470 2471 .. code-block:: c++ 2472 2473 false: true: 2474 switch (fool) { vs. switch (fool) { 2475 case 1: case 1: 2476 bar(); bar(); 2477 break; break; 2478 default: default: 2479 plop(); plop(); 2480 } } 2481 2482**IndentExternBlock** (``IndentExternBlockStyle``) 2483 IndentExternBlockStyle is the type of indenting of extern blocks. 2484 2485 Possible values: 2486 2487 * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``) 2488 Backwards compatible with AfterExternBlock's indenting. 2489 2490 .. code-block:: c++ 2491 2492 IndentExternBlock: AfterExternBlock 2493 BraceWrapping.AfterExternBlock: true 2494 extern "C" 2495 { 2496 void foo(); 2497 } 2498 2499 2500 .. code-block:: c++ 2501 2502 IndentExternBlock: AfterExternBlock 2503 BraceWrapping.AfterExternBlock: false 2504 extern "C" { 2505 void foo(); 2506 } 2507 2508 * ``IEBS_NoIndent`` (in configuration: ``NoIndent``) 2509 Does not indent extern blocks. 2510 2511 .. code-block:: c++ 2512 2513 extern "C" { 2514 void foo(); 2515 } 2516 2517 * ``IEBS_Indent`` (in configuration: ``Indent``) 2518 Indents extern blocks. 2519 2520 .. code-block:: c++ 2521 2522 extern "C" { 2523 void foo(); 2524 } 2525 2526 2527 2528**IndentGotoLabels** (``bool``) 2529 Indent goto labels. 2530 2531 When ``false``, goto labels are flushed left. 2532 2533 .. code-block:: c++ 2534 2535 true: false: 2536 int f() { vs. int f() { 2537 if (foo()) { if (foo()) { 2538 label1: label1: 2539 bar(); bar(); 2540 } } 2541 label2: label2: 2542 return 1; return 1; 2543 } } 2544 2545**IndentPPDirectives** (``PPDirectiveIndentStyle``) 2546 The preprocessor directive indenting style to use. 2547 2548 Possible values: 2549 2550 * ``PPDIS_None`` (in configuration: ``None``) 2551 Does not indent any directives. 2552 2553 .. code-block:: c++ 2554 2555 #if FOO 2556 #if BAR 2557 #include <foo> 2558 #endif 2559 #endif 2560 2561 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``) 2562 Indents directives after the hash. 2563 2564 .. code-block:: c++ 2565 2566 #if FOO 2567 # if BAR 2568 # include <foo> 2569 # endif 2570 #endif 2571 2572 * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) 2573 Indents directives before the hash. 2574 2575 .. code-block:: c++ 2576 2577 #if FOO 2578 #if BAR 2579 #include <foo> 2580 #endif 2581 #endif 2582 2583 2584 2585**IndentRequires** (``bool``) 2586 Indent the requires clause in a template 2587 2588 .. code-block:: c++ 2589 2590 true: 2591 template <typename It> 2592 requires Iterator<It> 2593 void sort(It begin, It end) { 2594 //.... 2595 } 2596 2597 false: 2598 template <typename It> 2599 requires Iterator<It> 2600 void sort(It begin, It end) { 2601 //.... 2602 } 2603 2604**IndentWidth** (``unsigned``) 2605 The number of columns to use for indentation. 2606 2607 .. code-block:: c++ 2608 2609 IndentWidth: 3 2610 2611 void f() { 2612 someFunction(); 2613 if (true, false) { 2614 f(); 2615 } 2616 } 2617 2618**IndentWrappedFunctionNames** (``bool``) 2619 Indent if a function definition or declaration is wrapped after the 2620 type. 2621 2622 .. code-block:: c++ 2623 2624 true: 2625 LoooooooooooooooooooooooooooooooooooooooongReturnType 2626 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 2627 2628 false: 2629 LoooooooooooooooooooooooooooooooooooooooongReturnType 2630 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 2631 2632**InsertTrailingCommas** (``TrailingCommaStyle``) 2633 If set to ``TCS_Wrapped`` will insert trailing commas in container 2634 literals (arrays and objects) that wrap across multiple lines. 2635 It is currently only available for JavaScript 2636 and disabled by default ``TCS_None``. 2637 ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` 2638 as inserting the comma disables bin-packing. 2639 2640 .. code-block:: c++ 2641 2642 TSC_Wrapped: 2643 const someArray = [ 2644 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2645 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2646 aaaaaaaaaaaaaaaaaaaaaaaaaa, 2647 // ^ inserted 2648 ] 2649 2650 Possible values: 2651 2652 * ``TCS_None`` (in configuration: ``None``) 2653 Do not insert trailing commas. 2654 2655 * ``TCS_Wrapped`` (in configuration: ``Wrapped``) 2656 Insert trailing commas in container literals that were wrapped over 2657 multiple lines. Note that this is conceptually incompatible with 2658 bin-packing, because the trailing comma is used as an indicator 2659 that a container should be formatted one-per-line (i.e. not bin-packed). 2660 So inserting a trailing comma counteracts bin-packing. 2661 2662 2663 2664**JavaImportGroups** (``std::vector<std::string>``) 2665 A vector of prefixes ordered by the desired groups for Java imports. 2666 2667 One group's prefix can be a subset of another - the longest prefix is 2668 always matched. Within a group, the imports are ordered lexicographically. 2669 Static imports are grouped separately and follow the same group rules. 2670 By default, static imports are placed before non-static imports, 2671 but this behavior is changed by another option, 2672 ``SortJavaStaticImport``. 2673 2674 In the .clang-format configuration file, this can be configured like 2675 in the following yaml example. This will result in imports being 2676 formatted as in the Java example below. 2677 2678 .. code-block:: yaml 2679 2680 JavaImportGroups: ['com.example', 'com', 'org'] 2681 2682 2683 .. code-block:: java 2684 2685 import static com.example.function1; 2686 2687 import static com.test.function2; 2688 2689 import static org.example.function3; 2690 2691 import com.example.ClassA; 2692 import com.example.Test; 2693 import com.example.a.ClassB; 2694 2695 import com.test.ClassC; 2696 2697 import org.example.ClassD; 2698 2699**JavaScriptQuotes** (``JavaScriptQuoteStyle``) 2700 The JavaScriptQuoteStyle to use for JavaScript strings. 2701 2702 Possible values: 2703 2704 * ``JSQS_Leave`` (in configuration: ``Leave``) 2705 Leave string quotes as they are. 2706 2707 .. code-block:: js 2708 2709 string1 = "foo"; 2710 string2 = 'bar'; 2711 2712 * ``JSQS_Single`` (in configuration: ``Single``) 2713 Always use single quotes. 2714 2715 .. code-block:: js 2716 2717 string1 = 'foo'; 2718 string2 = 'bar'; 2719 2720 * ``JSQS_Double`` (in configuration: ``Double``) 2721 Always use double quotes. 2722 2723 .. code-block:: js 2724 2725 string1 = "foo"; 2726 string2 = "bar"; 2727 2728 2729 2730**JavaScriptWrapImports** (``bool``) 2731 Whether to wrap JavaScript import/export statements. 2732 2733 .. code-block:: js 2734 2735 true: 2736 import { 2737 VeryLongImportsAreAnnoying, 2738 VeryLongImportsAreAnnoying, 2739 VeryLongImportsAreAnnoying, 2740 } from 'some/module.js' 2741 2742 false: 2743 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" 2744 2745**KeepEmptyLinesAtTheStartOfBlocks** (``bool``) 2746 If true, the empty line at the start of blocks is kept. 2747 2748 .. code-block:: c++ 2749 2750 true: false: 2751 if (foo) { vs. if (foo) { 2752 bar(); 2753 bar(); } 2754 } 2755 2756**Language** (``LanguageKind``) 2757 Language, this format style is targeted at. 2758 2759 Possible values: 2760 2761 * ``LK_None`` (in configuration: ``None``) 2762 Do not use. 2763 2764 * ``LK_Cpp`` (in configuration: ``Cpp``) 2765 Should be used for C, C++. 2766 2767 * ``LK_CSharp`` (in configuration: ``CSharp``) 2768 Should be used for C#. 2769 2770 * ``LK_Java`` (in configuration: ``Java``) 2771 Should be used for Java. 2772 2773 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 2774 Should be used for JavaScript. 2775 2776 * ``LK_ObjC`` (in configuration: ``ObjC``) 2777 Should be used for Objective-C, Objective-C++. 2778 2779 * ``LK_Proto`` (in configuration: ``Proto``) 2780 Should be used for Protocol Buffers 2781 (https://developers.google.com/protocol-buffers/). 2782 2783 * ``LK_TableGen`` (in configuration: ``TableGen``) 2784 Should be used for TableGen code. 2785 2786 * ``LK_TextProto`` (in configuration: ``TextProto``) 2787 Should be used for Protocol Buffer messages in text format 2788 (https://developers.google.com/protocol-buffers/). 2789 2790 2791 2792**MacroBlockBegin** (``std::string``) 2793 A regular expression matching macros that start a block. 2794 2795 .. code-block:: c++ 2796 2797 # With: 2798 MacroBlockBegin: "^NS_MAP_BEGIN|\ 2799 NS_TABLE_HEAD$" 2800 MacroBlockEnd: "^\ 2801 NS_MAP_END|\ 2802 NS_TABLE_.*_END$" 2803 2804 NS_MAP_BEGIN 2805 foo(); 2806 NS_MAP_END 2807 2808 NS_TABLE_HEAD 2809 bar(); 2810 NS_TABLE_FOO_END 2811 2812 # Without: 2813 NS_MAP_BEGIN 2814 foo(); 2815 NS_MAP_END 2816 2817 NS_TABLE_HEAD 2818 bar(); 2819 NS_TABLE_FOO_END 2820 2821**MacroBlockEnd** (``std::string``) 2822 A regular expression matching macros that end a block. 2823 2824**MaxEmptyLinesToKeep** (``unsigned``) 2825 The maximum number of consecutive empty lines to keep. 2826 2827 .. code-block:: c++ 2828 2829 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 2830 int f() { int f() { 2831 int = 1; int i = 1; 2832 i = foo(); 2833 i = foo(); return i; 2834 } 2835 return i; 2836 } 2837 2838**NamespaceIndentation** (``NamespaceIndentationKind``) 2839 The indentation used for namespaces. 2840 2841 Possible values: 2842 2843 * ``NI_None`` (in configuration: ``None``) 2844 Don't indent in namespaces. 2845 2846 .. code-block:: c++ 2847 2848 namespace out { 2849 int i; 2850 namespace in { 2851 int i; 2852 } 2853 } 2854 2855 * ``NI_Inner`` (in configuration: ``Inner``) 2856 Indent only in inner namespaces (nested in other namespaces). 2857 2858 .. code-block:: c++ 2859 2860 namespace out { 2861 int i; 2862 namespace in { 2863 int i; 2864 } 2865 } 2866 2867 * ``NI_All`` (in configuration: ``All``) 2868 Indent in all namespaces. 2869 2870 .. code-block:: c++ 2871 2872 namespace out { 2873 int i; 2874 namespace in { 2875 int i; 2876 } 2877 } 2878 2879 2880 2881**NamespaceMacros** (``std::vector<std::string>``) 2882 A vector of macros which are used to open namespace blocks. 2883 2884 These are expected to be macros of the form: 2885 2886 .. code-block:: c++ 2887 2888 NAMESPACE(<namespace-name>, ...) { 2889 <namespace-content> 2890 } 2891 2892 For example: TESTSUITE 2893 2894**ObjCBinPackProtocolList** (``BinPackStyle``) 2895 Controls bin-packing Objective-C protocol conformance list 2896 items into as few lines as possible when they go over ``ColumnLimit``. 2897 2898 If ``Auto`` (the default), delegates to the value in 2899 ``BinPackParameters``. If that is ``true``, bin-packs Objective-C 2900 protocol conformance list items into as few lines as possible 2901 whenever they go over ``ColumnLimit``. 2902 2903 If ``Always``, always bin-packs Objective-C protocol conformance 2904 list items into as few lines as possible whenever they go over 2905 ``ColumnLimit``. 2906 2907 If ``Never``, lays out Objective-C protocol conformance list items 2908 onto individual lines whenever they go over ``ColumnLimit``. 2909 2910 2911 .. code-block:: objc 2912 2913 Always (or Auto, if BinPackParameters=true): 2914 @interface ccccccccccccc () < 2915 ccccccccccccc, ccccccccccccc, 2916 ccccccccccccc, ccccccccccccc> { 2917 } 2918 2919 Never (or Auto, if BinPackParameters=false): 2920 @interface ddddddddddddd () < 2921 ddddddddddddd, 2922 ddddddddddddd, 2923 ddddddddddddd, 2924 ddddddddddddd> { 2925 } 2926 2927 Possible values: 2928 2929 * ``BPS_Auto`` (in configuration: ``Auto``) 2930 Automatically determine parameter bin-packing behavior. 2931 2932 * ``BPS_Always`` (in configuration: ``Always``) 2933 Always bin-pack parameters. 2934 2935 * ``BPS_Never`` (in configuration: ``Never``) 2936 Never bin-pack parameters. 2937 2938 2939 2940**ObjCBlockIndentWidth** (``unsigned``) 2941 The number of characters to use for indentation of ObjC blocks. 2942 2943 .. code-block:: objc 2944 2945 ObjCBlockIndentWidth: 4 2946 2947 [operation setCompletionBlock:^{ 2948 [self onOperationDone]; 2949 }]; 2950 2951**ObjCBreakBeforeNestedBlockParam** (``bool``) 2952 Break parameters list into lines when there is nested block 2953 parameters in a function call. 2954 2955 .. code-block:: c++ 2956 2957 false: 2958 - (void)_aMethod 2959 { 2960 [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber 2961 *u, NSNumber *v) { 2962 u = c; 2963 }] 2964 } 2965 true: 2966 - (void)_aMethod 2967 { 2968 [self.test1 t:self 2969 w:self 2970 callback:^(typeof(self) self, NSNumber *u, NSNumber *v) { 2971 u = c; 2972 }] 2973 } 2974 2975**ObjCSpaceAfterProperty** (``bool``) 2976 Add a space after ``@property`` in Objective-C, i.e. use 2977 ``@property (readonly)`` instead of ``@property(readonly)``. 2978 2979**ObjCSpaceBeforeProtocolList** (``bool``) 2980 Add a space in front of an Objective-C protocol list, i.e. use 2981 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 2982 2983**PenaltyBreakAssignment** (``unsigned``) 2984 The penalty for breaking around an assignment operator. 2985 2986**PenaltyBreakBeforeFirstCallParameter** (``unsigned``) 2987 The penalty for breaking a function call after ``call(``. 2988 2989**PenaltyBreakComment** (``unsigned``) 2990 The penalty for each line break introduced inside a comment. 2991 2992**PenaltyBreakFirstLessLess** (``unsigned``) 2993 The penalty for breaking before the first ``<<``. 2994 2995**PenaltyBreakString** (``unsigned``) 2996 The penalty for each line break introduced inside a string literal. 2997 2998**PenaltyBreakTemplateDeclaration** (``unsigned``) 2999 The penalty for breaking after template declaration. 3000 3001**PenaltyExcessCharacter** (``unsigned``) 3002 The penalty for each character outside of the column limit. 3003 3004**PenaltyIndentedWhitespace** (``unsigned``) 3005 Penalty for each character of whitespace indentation 3006 (counted relative to leading non-whitespace column). 3007 3008**PenaltyReturnTypeOnItsOwnLine** (``unsigned``) 3009 Penalty for putting the return type of a function onto its own 3010 line. 3011 3012**PointerAlignment** (``PointerAlignmentStyle``) 3013 Pointer and reference alignment style. 3014 3015 Possible values: 3016 3017 * ``PAS_Left`` (in configuration: ``Left``) 3018 Align pointer to the left. 3019 3020 .. code-block:: c++ 3021 3022 int* a; 3023 3024 * ``PAS_Right`` (in configuration: ``Right``) 3025 Align pointer to the right. 3026 3027 .. code-block:: c++ 3028 3029 int *a; 3030 3031 * ``PAS_Middle`` (in configuration: ``Middle``) 3032 Align pointer in the middle. 3033 3034 .. code-block:: c++ 3035 3036 int * a; 3037 3038 3039 3040**RawStringFormats** (``std::vector<RawStringFormat>``) 3041 Defines hints for detecting supported languages code blocks in raw 3042 strings. 3043 3044 A raw string with a matching delimiter or a matching enclosing function 3045 name will be reformatted assuming the specified language based on the 3046 style for that language defined in the .clang-format file. If no style has 3047 been defined in the .clang-format file for the specific language, a 3048 predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not 3049 found, the formatting is based on llvm style. A matching delimiter takes 3050 precedence over a matching enclosing function name for determining the 3051 language of the raw string contents. 3052 3053 If a canonical delimiter is specified, occurrences of other delimiters for 3054 the same language will be updated to the canonical if possible. 3055 3056 There should be at most one specification per language and each delimiter 3057 and enclosing function should not occur in multiple specifications. 3058 3059 To configure this in the .clang-format file, use: 3060 3061 .. code-block:: yaml 3062 3063 RawStringFormats: 3064 - Language: TextProto 3065 Delimiters: 3066 - 'pb' 3067 - 'proto' 3068 EnclosingFunctions: 3069 - 'PARSE_TEXT_PROTO' 3070 BasedOnStyle: google 3071 - Language: Cpp 3072 Delimiters: 3073 - 'cc' 3074 - 'cpp' 3075 BasedOnStyle: llvm 3076 CanonicalDelimiter: 'cc' 3077 3078**ReflowComments** (``bool``) 3079 If ``true``, clang-format will attempt to re-flow comments. 3080 3081 .. code-block:: c++ 3082 3083 false: 3084 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 3085 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 3086 3087 true: 3088 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 3089 // information 3090 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 3091 * information */ 3092 3093**ShortNamespaceLines** (``unsigned``) 3094 The maximal number of unwrapped lines that a short namespace spans. 3095 Defaults to 1. 3096 3097 This determines the maximum length of short namespaces by counting 3098 unwrapped lines (i.e. containing neither opening nor closing 3099 namespace brace) and makes "FixNamespaceComments" omit adding 3100 end comments for those. 3101 3102 .. code-block:: c++ 3103 3104 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 3105 namespace a { namespace a { 3106 int foo; int foo; 3107 } } // namespace a 3108 3109 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 3110 namespace b { namespace b { 3111 int foo; int foo; 3112 int bar; int bar; 3113 } // namespace b } // namespace b 3114 3115**SortIncludes** (``SortIncludesOptions``) 3116 Controls if and how clang-format will sort ``#includes``. 3117 If ``Never``, includes are never sorted. 3118 If ``CaseInsensitive``, includes are sorted in an ASCIIbetical or case 3119 insensitive fashion. 3120 If ``CaseSensitive``, includes are sorted in an alphabetical or case 3121 sensitive fashion. 3122 3123 Possible values: 3124 3125 * ``SI_Never`` (in configuration: ``Never``) 3126 Includes are never sorted. 3127 3128 .. code-block:: c++ 3129 3130 #include "B/A.h" 3131 #include "A/B.h" 3132 #include "a/b.h" 3133 #include "A/b.h" 3134 #include "B/a.h" 3135 3136 * ``SI_CaseSensitive`` (in configuration: ``CaseSensitive``) 3137 Includes are sorted in an ASCIIbetical or case sensitive fashion. 3138 3139 .. code-block:: c++ 3140 3141 #include "A/B.h" 3142 #include "A/b.h" 3143 #include "B/A.h" 3144 #include "B/a.h" 3145 #include "a/b.h" 3146 3147 * ``SI_CaseInsensitive`` (in configuration: ``CaseInsensitive``) 3148 Includes are sorted in an alphabetical or case insensitive fashion. 3149 3150 .. code-block:: c++ 3151 3152 #include "A/B.h" 3153 #include "A/b.h" 3154 #include "a/b.h" 3155 #include "B/A.h" 3156 #include "B/a.h" 3157 3158 3159 3160**SortJavaStaticImport** (``SortJavaStaticImportOptions``) 3161 When sorting Java imports, by default static imports are placed before 3162 non-static imports. If ``JavaStaticImportAfterImport`` is ``After``, 3163 static imports are placed after non-static imports. 3164 3165 Possible values: 3166 3167 * ``SJSIO_Before`` (in configuration: ``Before``) 3168 Static imports are placed before non-static imports. 3169 3170 .. code-block:: java 3171 3172 import static org.example.function1; 3173 3174 import org.example.ClassA; 3175 3176 * ``SJSIO_After`` (in configuration: ``After``) 3177 Static imports are placed after non-static imports. 3178 3179 .. code-block:: java 3180 3181 import org.example.ClassA; 3182 3183 import static org.example.function1; 3184 3185 3186 3187**SortUsingDeclarations** (``bool``) 3188 If ``true``, clang-format will sort using declarations. 3189 3190 The order of using declarations is defined as follows: 3191 Split the strings by "::" and discard any initial empty strings. The last 3192 element of each list is a non-namespace name; all others are namespace 3193 names. Sort the lists of names lexicographically, where the sort order of 3194 individual names is that all non-namespace names come before all namespace 3195 names, and within those groups, names are in case-insensitive 3196 lexicographic order. 3197 3198 .. code-block:: c++ 3199 3200 false: true: 3201 using std::cout; vs. using std::cin; 3202 using std::cin; using std::cout; 3203 3204**SpaceAfterCStyleCast** (``bool``) 3205 If ``true``, a space is inserted after C style casts. 3206 3207 .. code-block:: c++ 3208 3209 true: false: 3210 (int) i; vs. (int)i; 3211 3212**SpaceAfterLogicalNot** (``bool``) 3213 If ``true``, a space is inserted after the logical not operator (``!``). 3214 3215 .. code-block:: c++ 3216 3217 true: false: 3218 ! someExpression(); vs. !someExpression(); 3219 3220**SpaceAfterTemplateKeyword** (``bool``) 3221 If ``true``, a space will be inserted after the 'template' keyword. 3222 3223 .. code-block:: c++ 3224 3225 true: false: 3226 template <int> void foo(); vs. template<int> void foo(); 3227 3228**SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) 3229 Defines in which cases to put a space before or after pointer qualifiers 3230 3231 Possible values: 3232 3233 * ``SAPQ_Default`` (in configuration: ``Default``) 3234 Don't ensure spaces around pointer qualifiers and use PointerAlignment 3235 instead. 3236 3237 .. code-block:: c++ 3238 3239 PointerAlignment: Left PointerAlignment: Right 3240 void* const* x = NULL; vs. void *const *x = NULL; 3241 3242 * ``SAPQ_Before`` (in configuration: ``Before``) 3243 Ensure that there is a space before pointer qualifiers. 3244 3245 .. code-block:: c++ 3246 3247 PointerAlignment: Left PointerAlignment: Right 3248 void* const* x = NULL; vs. void * const *x = NULL; 3249 3250 * ``SAPQ_After`` (in configuration: ``After``) 3251 Ensure that there is a space after pointer qualifiers. 3252 3253 .. code-block:: c++ 3254 3255 PointerAlignment: Left PointerAlignment: Right 3256 void* const * x = NULL; vs. void *const *x = NULL; 3257 3258 * ``SAPQ_Both`` (in configuration: ``Both``) 3259 Ensure that there is a space both before and after pointer qualifiers. 3260 3261 .. code-block:: c++ 3262 3263 PointerAlignment: Left PointerAlignment: Right 3264 void* const * x = NULL; vs. void * const *x = NULL; 3265 3266 3267 3268**SpaceBeforeAssignmentOperators** (``bool``) 3269 If ``false``, spaces will be removed before assignment operators. 3270 3271 .. code-block:: c++ 3272 3273 true: false: 3274 int a = 5; vs. int a= 5; 3275 a += 42; a+= 42; 3276 3277**SpaceBeforeCaseColon** (``bool``) 3278 If ``false``, spaces will be removed before case colon. 3279 3280 .. code-block:: c++ 3281 3282 true: false 3283 switch (x) { vs. switch (x) { 3284 case 1 : break; case 1: break; 3285 } } 3286 3287**SpaceBeforeCpp11BracedList** (``bool``) 3288 If ``true``, a space will be inserted before a C++11 braced list 3289 used to initialize an object (after the preceding identifier or type). 3290 3291 .. code-block:: c++ 3292 3293 true: false: 3294 Foo foo { bar }; vs. Foo foo{ bar }; 3295 Foo {}; Foo{}; 3296 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; 3297 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; 3298 3299**SpaceBeforeCtorInitializerColon** (``bool``) 3300 If ``false``, spaces will be removed before constructor initializer 3301 colon. 3302 3303 .. code-block:: c++ 3304 3305 true: false: 3306 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} 3307 3308**SpaceBeforeInheritanceColon** (``bool``) 3309 If ``false``, spaces will be removed before inheritance colon. 3310 3311 .. code-block:: c++ 3312 3313 true: false: 3314 class Foo : Bar {} vs. class Foo: Bar {} 3315 3316**SpaceBeforeParens** (``SpaceBeforeParensOptions``) 3317 Defines in which cases to put a space before opening parentheses. 3318 3319 Possible values: 3320 3321 * ``SBPO_Never`` (in configuration: ``Never``) 3322 Never put a space before opening parentheses. 3323 3324 .. code-block:: c++ 3325 3326 void f() { 3327 if(true) { 3328 f(); 3329 } 3330 } 3331 3332 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 3333 Put a space before opening parentheses only after control statement 3334 keywords (``for/if/while...``). 3335 3336 .. code-block:: c++ 3337 3338 void f() { 3339 if (true) { 3340 f(); 3341 } 3342 } 3343 3344 * ``SBPO_ControlStatementsExceptForEachMacros`` (in configuration: ``ControlStatementsExceptForEachMacros``) 3345 Same as ``SBPO_ControlStatements`` except this option doesn't apply to 3346 ForEach macros. This is useful in projects where ForEach macros are 3347 treated as function calls instead of control statements. 3348 3349 .. code-block:: c++ 3350 3351 void f() { 3352 Q_FOREACH(...) { 3353 f(); 3354 } 3355 } 3356 3357 * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``) 3358 Put a space before opening parentheses only if the parentheses are not 3359 empty i.e. '()' 3360 3361 .. code-block:: c++ 3362 3363 void() { 3364 if (true) { 3365 f(); 3366 g (x, y, z); 3367 } 3368 } 3369 3370 * ``SBPO_Always`` (in configuration: ``Always``) 3371 Always put a space before opening parentheses, except when it's 3372 prohibited by the syntax rules (in function-like macro definitions) or 3373 when determined by other style rules (after unary operators, opening 3374 parentheses, etc.) 3375 3376 .. code-block:: c++ 3377 3378 void f () { 3379 if (true) { 3380 f (); 3381 } 3382 } 3383 3384 3385 3386**SpaceBeforeRangeBasedForLoopColon** (``bool``) 3387 If ``false``, spaces will be removed before range-based for loop 3388 colon. 3389 3390 .. code-block:: c++ 3391 3392 true: false: 3393 for (auto v : values) {} vs. for(auto v: values) {} 3394 3395**SpaceBeforeSquareBrackets** (``bool``) 3396 If ``true``, spaces will be before ``[``. 3397 Lambdas will not be affected. Only the first ``[`` will get a space added. 3398 3399 .. code-block:: c++ 3400 3401 true: false: 3402 int a [5]; vs. int a[5]; 3403 int a [5][5]; vs. int a[5][5]; 3404 3405**SpaceInEmptyBlock** (``bool``) 3406 If ``true``, spaces will be inserted into ``{}``. 3407 3408 .. code-block:: c++ 3409 3410 true: false: 3411 void f() { } vs. void f() {} 3412 while (true) { } while (true) {} 3413 3414**SpaceInEmptyParentheses** (``bool``) 3415 If ``true``, spaces may be inserted into ``()``. 3416 3417 .. code-block:: c++ 3418 3419 true: false: 3420 void f( ) { vs. void f() { 3421 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; 3422 if (true) { if (true) { 3423 f( ); f(); 3424 } } 3425 } } 3426 3427**SpacesBeforeTrailingComments** (``unsigned``) 3428 The number of spaces before trailing line comments 3429 (``//`` - comments). 3430 3431 This does not affect trailing block comments (``/*`` - comments) as 3432 those commonly have different usage patterns and a number of special 3433 cases. 3434 3435 .. code-block:: c++ 3436 3437 SpacesBeforeTrailingComments: 3 3438 void f() { 3439 if (true) { // foo1 3440 f(); // bar 3441 } // foo 3442 } 3443 3444**SpacesInAngles** (``bool``) 3445 If ``true``, spaces will be inserted after ``<`` and before ``>`` 3446 in template argument lists. 3447 3448 .. code-block:: c++ 3449 3450 true: false: 3451 static_cast< int >(arg); vs. static_cast<int>(arg); 3452 std::function< void(int) > fct; std::function<void(int)> fct; 3453 3454**SpacesInCStyleCastParentheses** (``bool``) 3455 If ``true``, spaces may be inserted into C style casts. 3456 3457 .. code-block:: c++ 3458 3459 true: false: 3460 x = ( int32 )y vs. x = (int32)y 3461 3462**SpacesInConditionalStatement** (``bool``) 3463 If ``true``, spaces will be inserted around if/for/switch/while 3464 conditions. 3465 3466 .. code-block:: c++ 3467 3468 true: false: 3469 if ( a ) { ... } vs. if (a) { ... } 3470 while ( i < 5 ) { ... } while (i < 5) { ... } 3471 3472**SpacesInContainerLiterals** (``bool``) 3473 If ``true``, spaces are inserted inside container literals (e.g. 3474 ObjC and Javascript array and dict literals). 3475 3476 .. code-block:: js 3477 3478 true: false: 3479 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; 3480 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); 3481 3482**SpacesInLineCommentPrefix** (``SpacesInLineComment``) 3483 How many spaces are allowed at the start of a line comment. To disable the 3484 maximum set it to ``-1``, apart from that the maximum takes precedence 3485 over the minimum. 3486 Minimum = 1 Maximum = -1 3487 // One space is forced 3488 3489 // but more spaces are possible 3490 3491 Minimum = 0 3492 Maximum = 0 3493 //Forces to start every comment directly after the slashes 3494 3495 Note that in line comment sections the relative indent of the subsequent 3496 lines is kept, that means the following: 3497 3498 .. code-block:: c++ 3499 3500 before: after: 3501 Minimum: 1 3502 //if (b) { // if (b) { 3503 // return true; // return true; 3504 //} // } 3505 3506 Maximum: 0 3507 /// List: ///List: 3508 /// - Foo /// - Foo 3509 /// - Bar /// - Bar 3510 3511 Nested configuration flags: 3512 3513 3514 * ``unsigned Minimum`` The minimum number of spaces at the start of the comment. 3515 3516 * ``unsigned Maximum`` The maximum number of spaces at the start of the comment. 3517 3518 3519**SpacesInParentheses** (``bool``) 3520 If ``true``, spaces will be inserted after ``(`` and before ``)``. 3521 3522 .. code-block:: c++ 3523 3524 true: false: 3525 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; 3526 3527**SpacesInSquareBrackets** (``bool``) 3528 If ``true``, spaces will be inserted after ``[`` and before ``]``. 3529 Lambdas without arguments or unspecified size array declarations will not 3530 be affected. 3531 3532 .. code-block:: c++ 3533 3534 true: false: 3535 int a[ 5 ]; vs. int a[5]; 3536 std::unique_ptr<int[]> foo() {} // Won't be affected 3537 3538**Standard** (``LanguageStandard``) 3539 Parse and format C++ constructs compatible with this standard. 3540 3541 .. code-block:: c++ 3542 3543 c++03: latest: 3544 vector<set<int> > x; vs. vector<set<int>> x; 3545 3546 Possible values: 3547 3548 * ``LS_Cpp03`` (in configuration: ``c++03``) 3549 Parse and format as C++03. 3550 ``Cpp03`` is a deprecated alias for ``c++03`` 3551 3552 * ``LS_Cpp11`` (in configuration: ``c++11``) 3553 Parse and format as C++11. 3554 3555 * ``LS_Cpp14`` (in configuration: ``c++14``) 3556 Parse and format as C++14. 3557 3558 * ``LS_Cpp17`` (in configuration: ``c++17``) 3559 Parse and format as C++17. 3560 3561 * ``LS_Cpp20`` (in configuration: ``c++20``) 3562 Parse and format as C++20. 3563 3564 * ``LS_Latest`` (in configuration: ``Latest``) 3565 Parse and format using the latest supported language version. 3566 ``Cpp11`` is a deprecated alias for ``Latest`` 3567 3568 * ``LS_Auto`` (in configuration: ``Auto``) 3569 Automatic detection based on the input. 3570 3571 3572 3573**StatementAttributeLikeMacros** (``std::vector<std::string>``) 3574 Macros which are ignored in front of a statement, as if they were an 3575 attribute. So that they are not parsed as identifier, for example for Qts 3576 emit. 3577 3578 .. code-block:: c++ 3579 3580 AlignConsecutiveDeclarations: true 3581 StatementAttributeLikeMacros: [] 3582 unsigned char data = 'x'; 3583 emit signal(data); // This is parsed as variable declaration. 3584 3585 AlignConsecutiveDeclarations: true 3586 StatementAttributeLikeMacros: [emit] 3587 unsigned char data = 'x'; 3588 emit signal(data); // Now it's fine again. 3589 3590**StatementMacros** (``std::vector<std::string>``) 3591 A vector of macros that should be interpreted as complete 3592 statements. 3593 3594 Typical macros are expressions, and require a semi-colon to be 3595 added; sometimes this is not the case, and this allows to make 3596 clang-format aware of such cases. 3597 3598 For example: Q_UNUSED 3599 3600**TabWidth** (``unsigned``) 3601 The number of columns used for tab stops. 3602 3603**TypenameMacros** (``std::vector<std::string>``) 3604 A vector of macros that should be interpreted as type declarations 3605 instead of as function calls. 3606 3607 These are expected to be macros of the form: 3608 3609 .. code-block:: c++ 3610 3611 STACK_OF(...) 3612 3613 In the .clang-format configuration file, this can be configured like: 3614 3615 .. code-block:: yaml 3616 3617 TypenameMacros: ['STACK_OF', 'LIST'] 3618 3619 For example: OpenSSL STACK_OF, BSD LIST_ENTRY. 3620 3621**UseCRLF** (``bool``) 3622 Use ``\r\n`` instead of ``\n`` for line breaks. 3623 Also used as fallback if ``DeriveLineEnding`` is true. 3624 3625**UseTab** (``UseTabStyle``) 3626 The way to use tab characters in the resulting file. 3627 3628 Possible values: 3629 3630 * ``UT_Never`` (in configuration: ``Never``) 3631 Never use tab. 3632 3633 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 3634 Use tabs only for indentation. 3635 3636 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``) 3637 Fill all leading whitespace with tabs, and use spaces for alignment that 3638 appears within a line (e.g. consecutive assignments and declarations). 3639 3640 * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``) 3641 Use tabs for line continuation and indentation, and spaces for 3642 alignment. 3643 3644 * ``UT_Always`` (in configuration: ``Always``) 3645 Use tabs whenever we need to fill whitespace that spans at least from 3646 one tab stop to the next one. 3647 3648 3649 3650**WhitespaceSensitiveMacros** (``std::vector<std::string>``) 3651 A vector of macros which are whitespace-sensitive and should not 3652 be touched. 3653 3654 These are expected to be macros of the form: 3655 3656 .. code-block:: c++ 3657 3658 STRINGIZE(...) 3659 3660 In the .clang-format configuration file, this can be configured like: 3661 3662 .. code-block:: yaml 3663 3664 WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE'] 3665 3666 For example: BOOST_PP_STRINGIZE 3667 3668.. END_FORMAT_STYLE_OPTIONS 3669 3670Adding additional style options 3671=============================== 3672 3673Each additional style option adds costs to the clang-format project. Some of 3674these costs affect the clang-format development itself, as we need to make 3675sure that any given combination of options work and that new features don't 3676break any of the existing options in any way. There are also costs for end users 3677as options become less discoverable and people have to think about and make a 3678decision on options they don't really care about. 3679 3680The goal of the clang-format project is more on the side of supporting a 3681limited set of styles really well as opposed to supporting every single style 3682used by a codebase somewhere in the wild. Of course, we do want to support all 3683major projects and thus have established the following bar for adding style 3684options. Each new style option must .. 3685 3686 * be used in a project of significant size (have dozens of contributors) 3687 * have a publicly accessible style guide 3688 * have a person willing to contribute and maintain patches 3689 3690Examples 3691======== 3692 3693A style similar to the `Linux Kernel style 3694<https://www.kernel.org/doc/Documentation/CodingStyle>`_: 3695 3696.. code-block:: yaml 3697 3698 BasedOnStyle: LLVM 3699 IndentWidth: 8 3700 UseTab: Always 3701 BreakBeforeBraces: Linux 3702 AllowShortIfStatementsOnASingleLine: false 3703 IndentCaseLabels: false 3704 3705The result is (imagine that tabs are used for indentation here): 3706 3707.. code-block:: c++ 3708 3709 void test() 3710 { 3711 switch (x) { 3712 case 0: 3713 case 1: 3714 do_something(); 3715 break; 3716 case 2: 3717 do_something_else(); 3718 break; 3719 default: 3720 break; 3721 } 3722 if (condition) 3723 do_something_completely_different(); 3724 3725 if (x == y) { 3726 q(); 3727 } else if (x > y) { 3728 w(); 3729 } else { 3730 r(); 3731 } 3732 } 3733 3734A style similar to the default Visual Studio formatting style: 3735 3736.. code-block:: yaml 3737 3738 UseTab: Never 3739 IndentWidth: 4 3740 BreakBeforeBraces: Allman 3741 AllowShortIfStatementsOnASingleLine: false 3742 IndentCaseLabels: false 3743 ColumnLimit: 0 3744 3745The result is: 3746 3747.. code-block:: c++ 3748 3749 void test() 3750 { 3751 switch (suffix) 3752 { 3753 case 0: 3754 case 1: 3755 do_something(); 3756 break; 3757 case 2: 3758 do_something_else(); 3759 break; 3760 default: 3761 break; 3762 } 3763 if (condition) 3764 do_something_completely_different(); 3765 3766 if (x == y) 3767 { 3768 q(); 3769 } 3770 else if (x > y) 3771 { 3772 w(); 3773 } 3774 else 3775 { 3776 r(); 3777 } 3778 } 3779