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