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