1.. 2 !!!!NOTE!!!! 3 This file is automatically generated, in part. Do not edit the style options 4 in this file directly. Instead, modify them in include/clang/Format/Format.h 5 and run the docs/tools/dump_format_style.py script to update this file. 6 7.. raw:: html 8 9 <style type="text/css"> 10 .versionbadge { background-color: #1c913d; height: 20px; display: inline-block; min-width: 120px; text-align: center; border-radius: 5px; color: #FFFFFF; font-family: "Verdana,Geneva,DejaVu Sans,sans-serif"; } 11 </style> 12 13.. role:: versionbadge 14 15========================== 16Clang-Format Style Options 17========================== 18 19:doc:`ClangFormatStyleOptions` describes configurable formatting style options 20supported by :doc:`LibFormat` and :doc:`ClangFormat`. 21 22When using :program:`clang-format` command line utility or 23``clang::format::reformat(...)`` functions from code, one can either use one of 24the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or 25create a custom style by configuring specific style options. 26 27 28Configuring Style with clang-format 29=================================== 30 31:program:`clang-format` supports two ways to provide custom style options: 32directly specify style configuration in the ``-style=`` command line option or 33use ``-style=file`` and put style configuration in the ``.clang-format`` or 34``_clang-format`` file in the project directory. 35 36When using ``-style=file``, :program:`clang-format` for each input file will 37try to find the ``.clang-format`` file located in the closest parent directory 38of the input file. When the standard input is used, the search is started from 39the current directory. 40 41When using ``-style=file:<format_file_path>``, :program:`clang-format` for 42each input file will use the format file located at `<format_file_path>`. 43The path may be absolute or relative to the working directory. 44 45The ``.clang-format`` file uses YAML format: 46 47.. code-block:: yaml 48 49 key1: value1 50 key2: value2 51 # A comment. 52 ... 53 54The configuration file can consist of several sections each having different 55``Language:`` parameter denoting the programming language this section of the 56configuration is targeted at. See the description of the **Language** option 57below for the list of supported languages. The first section may have no 58language set, it will set the default style options for all languages. 59Configuration sections for specific language will override options set in the 60default section. 61 62When :program:`clang-format` formats a file, it auto-detects the language using 63the file name. When formatting standard input or a file that doesn't have the 64extension corresponding to its language, ``-assume-filename=`` option can be 65used to override the file name :program:`clang-format` uses to detect the 66language. 67 68An example of a configuration file for multiple languages: 69 70.. code-block:: yaml 71 72 --- 73 # We'll use defaults from the LLVM style, but with 4 columns indentation. 74 BasedOnStyle: LLVM 75 IndentWidth: 4 76 --- 77 Language: Cpp 78 # Force pointers to the type for C++. 79 DerivePointerAlignment: false 80 PointerAlignment: Left 81 --- 82 Language: JavaScript 83 # Use 100 columns for JS. 84 ColumnLimit: 100 85 --- 86 Language: Proto 87 # Don't format .proto files. 88 DisableFormat: true 89 --- 90 Language: CSharp 91 # Use 100 columns for C#. 92 ColumnLimit: 100 93 ... 94 95An easy way to get a valid ``.clang-format`` file containing all configuration 96options of a certain predefined style is: 97 98.. code-block:: console 99 100 clang-format -style=llvm -dump-config > .clang-format 101 102When specifying configuration in the ``-style=`` option, the same configuration 103is applied for all input files. The format of the configuration is: 104 105.. code-block:: console 106 107 -style='{key1: value1, key2: value2, ...}' 108 109 110Disabling Formatting on a Piece of Code 111======================================= 112 113Clang-format understands also special comments that switch formatting in a 114delimited range. The code between a comment ``// clang-format off`` or 115``/* clang-format off */`` up to a comment ``// clang-format on`` or 116``/* clang-format on */`` will not be formatted. The comments themselves will be 117formatted (aligned) normally. Also, a colon (``:``) and additional text may 118follow ``// clang-format off`` or ``// clang-format on`` to explain why 119clang-format is turned off or back on. 120 121.. code-block:: c++ 122 123 int formatted_code; 124 // clang-format off 125 void unformatted_code ; 126 // clang-format on 127 void formatted_code_again; 128 129 130Configuring Style in Code 131========================= 132 133When using ``clang::format::reformat(...)`` functions, the format is specified 134by supplying the `clang::format::FormatStyle 135<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_ 136structure. 137 138 139Configurable Format Style Options 140================================= 141 142This section lists the supported style options. Value type is specified for 143each option. For enumeration types possible values are specified both as a C++ 144enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in 145the configuration (without a prefix: ``Auto``). 146 147.. _BasedOnStyle: 148 149**BasedOnStyle** (``String``) :ref:`¶ <BasedOnStyle>` 150 The style used for all options not specifically set in the configuration. 151 152 This option is supported only in the :program:`clang-format` configuration 153 (both within ``-style='{...}'`` and the ``.clang-format`` file). 154 155 Possible values: 156 157 * ``LLVM`` 158 A style complying with the `LLVM coding standards 159 <https://llvm.org/docs/CodingStandards.html>`_ 160 * ``Google`` 161 A style complying with `Google's C++ style guide 162 <https://google.github.io/styleguide/cppguide.html>`_ 163 * ``Chromium`` 164 A style complying with `Chromium's style guide 165 <https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md>`_ 166 * ``Mozilla`` 167 A style complying with `Mozilla's style guide 168 <https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html>`_ 169 * ``WebKit`` 170 A style complying with `WebKit's style guide 171 <https://www.webkit.org/coding/coding-style.html>`_ 172 * ``Microsoft`` 173 A style complying with `Microsoft's style guide 174 <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference>`_ 175 * ``GNU`` 176 A style complying with the `GNU coding standards 177 <https://www.gnu.org/prep/standards/standards.html>`_ 178 * ``InheritParentConfig`` 179 Not a real style, but allows to use the ``.clang-format`` file from the 180 parent directory (or its parent if there is none). If there is no parent 181 file found it falls back to the ``fallback`` style, and applies the changes 182 to that. 183 184 With this option you can overwrite some parts of your main style for your 185 subdirectories. This is also possible through the command line, e.g.: 186 ``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}`` 187 188.. START_FORMAT_STYLE_OPTIONS 189 190.. _AccessModifierOffset: 191 192**AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3` :ref:`¶ <AccessModifierOffset>` 193 The extra indent or outdent of access modifiers, e.g. ``public:``. 194 195.. _AlignAfterOpenBracket: 196 197**AlignAfterOpenBracket** (``BracketAlignmentStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignAfterOpenBracket>` 198 If ``true``, horizontally aligns arguments after an open bracket. 199 200 This applies to round brackets (parentheses), angle brackets and square 201 brackets. 202 203 Possible values: 204 205 * ``BAS_Align`` (in configuration: ``Align``) 206 Align parameters on the open bracket, e.g.: 207 208 .. code-block:: c++ 209 210 someLongFunction(argument1, 211 argument2); 212 213 * ``BAS_DontAlign`` (in configuration: ``DontAlign``) 214 Don't align, instead use ``ContinuationIndentWidth``, e.g.: 215 216 .. code-block:: c++ 217 218 someLongFunction(argument1, 219 argument2); 220 221 * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``) 222 Always break after an open bracket, if the parameters don't fit 223 on a single line, e.g.: 224 225 .. code-block:: c++ 226 227 someLongFunction( 228 argument1, argument2); 229 230 * ``BAS_BlockIndent`` (in configuration: ``BlockIndent``) 231 Always break after an open bracket, if the parameters don't fit 232 on a single line. Closing brackets will be placed on a new line. 233 E.g.: 234 235 .. code-block:: c++ 236 237 someLongFunction( 238 argument1, argument2 239 ) 240 241 242 .. note:: 243 244 This currently only applies to braced initializer lists (when 245 ``Cpp11BracedListStyle`` is ``true``) and parentheses. 246 247 248 249.. _AlignArrayOfStructures: 250 251**AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>` 252 If not ``None``, when using initialization for an array of structs 253 aligns the fields into columns. 254 255 256 .. note:: 257 258 As of clang-format 15 this option only applied to arrays with equal 259 number of columns per row. 260 261 Possible values: 262 263 * ``AIAS_Left`` (in configuration: ``Left``) 264 Align array column and left justify the columns e.g.: 265 266 .. code-block:: c++ 267 268 struct test demo[] = 269 { 270 {56, 23, "hello"}, 271 {-1, 93463, "world"}, 272 {7, 5, "!!" } 273 }; 274 275 * ``AIAS_Right`` (in configuration: ``Right``) 276 Align array column and right justify the columns e.g.: 277 278 .. code-block:: c++ 279 280 struct test demo[] = 281 { 282 {56, 23, "hello"}, 283 {-1, 93463, "world"}, 284 { 7, 5, "!!"} 285 }; 286 287 * ``AIAS_None`` (in configuration: ``None``) 288 Don't align array initializer columns. 289 290 291 292.. _AlignConsecutiveAssignments: 293 294**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveAssignments>` 295 Style of aligning consecutive assignments. 296 297 ``Consecutive`` will result in formattings like: 298 299 .. code-block:: c++ 300 301 int a = 1; 302 int somelongname = 2; 303 double c = 3; 304 305 Nested configuration flags: 306 307 Alignment options. 308 309 They can also be read as a whole for compatibility. The choices are: 310 311 * ``None`` 312 * ``Consecutive`` 313 * ``AcrossEmptyLines`` 314 * ``AcrossComments`` 315 * ``AcrossEmptyLinesAndComments`` 316 317 For example, to align across empty lines and not across comments, either 318 of these work. 319 320 .. code-block:: c++ 321 322 AlignConsecutiveAssignments: AcrossEmptyLines 323 324 AlignConsecutiveAssignments: 325 Enabled: true 326 AcrossEmptyLines: true 327 AcrossComments: false 328 329 * ``bool Enabled`` Whether aligning is enabled. 330 331 .. code-block:: c++ 332 333 #define SHORT_NAME 42 334 #define LONGER_NAME 0x007f 335 #define EVEN_LONGER_NAME (2) 336 #define foo(x) (x * x) 337 #define bar(y, z) (y + z) 338 339 int a = 1; 340 int somelongname = 2; 341 double c = 3; 342 343 int aaaa : 1; 344 int b : 12; 345 int ccc : 8; 346 347 int aaaa = 12; 348 float b = 23; 349 std::string ccc; 350 351 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 352 353 .. code-block:: c++ 354 355 true: 356 int a = 1; 357 int somelongname = 2; 358 double c = 3; 359 360 int d = 3; 361 362 false: 363 int a = 1; 364 int somelongname = 2; 365 double c = 3; 366 367 int d = 3; 368 369 * ``bool AcrossComments`` Whether to align across comments. 370 371 .. code-block:: c++ 372 373 true: 374 int d = 3; 375 /* A comment. */ 376 double e = 4; 377 378 false: 379 int d = 3; 380 /* A comment. */ 381 double e = 4; 382 383 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 384 like ``+=`` are aligned along with ``=``. 385 386 .. code-block:: c++ 387 388 true: 389 a &= 2; 390 bbb = 2; 391 392 false: 393 a &= 2; 394 bbb = 2; 395 396 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 397 are aligned. 398 399 .. code-block:: c++ 400 401 true: 402 unsigned int f1(void); 403 void f2(void); 404 size_t f3(void); 405 406 false: 407 unsigned int f1(void); 408 void f2(void); 409 size_t f3(void); 410 411 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 412 aligned. 413 414 .. code-block:: c++ 415 416 true: 417 unsigned i; 418 int &r; 419 int *p; 420 int (*f)(); 421 422 false: 423 unsigned i; 424 int &r; 425 int *p; 426 int (*f)(); 427 428 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 429 operators are left-padded to the same length as long ones in order to 430 put all assignment operators to the right of the left hand side. 431 432 .. code-block:: c++ 433 434 true: 435 a >>= 2; 436 bbb = 2; 437 438 a = 2; 439 bbb >>= 2; 440 441 false: 442 a >>= 2; 443 bbb = 2; 444 445 a = 2; 446 bbb >>= 2; 447 448 449.. _AlignConsecutiveBitFields: 450 451**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11` :ref:`¶ <AlignConsecutiveBitFields>` 452 Style of aligning consecutive bit fields. 453 454 ``Consecutive`` will align the bitfield separators of consecutive lines. 455 This will result in formattings like: 456 457 .. code-block:: c++ 458 459 int aaaa : 1; 460 int b : 12; 461 int ccc : 8; 462 463 Nested configuration flags: 464 465 Alignment options. 466 467 They can also be read as a whole for compatibility. The choices are: 468 469 * ``None`` 470 * ``Consecutive`` 471 * ``AcrossEmptyLines`` 472 * ``AcrossComments`` 473 * ``AcrossEmptyLinesAndComments`` 474 475 For example, to align across empty lines and not across comments, either 476 of these work. 477 478 .. code-block:: c++ 479 480 AlignConsecutiveBitFields: AcrossEmptyLines 481 482 AlignConsecutiveBitFields: 483 Enabled: true 484 AcrossEmptyLines: true 485 AcrossComments: false 486 487 * ``bool Enabled`` Whether aligning is enabled. 488 489 .. code-block:: c++ 490 491 #define SHORT_NAME 42 492 #define LONGER_NAME 0x007f 493 #define EVEN_LONGER_NAME (2) 494 #define foo(x) (x * x) 495 #define bar(y, z) (y + z) 496 497 int a = 1; 498 int somelongname = 2; 499 double c = 3; 500 501 int aaaa : 1; 502 int b : 12; 503 int ccc : 8; 504 505 int aaaa = 12; 506 float b = 23; 507 std::string ccc; 508 509 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 510 511 .. code-block:: c++ 512 513 true: 514 int a = 1; 515 int somelongname = 2; 516 double c = 3; 517 518 int d = 3; 519 520 false: 521 int a = 1; 522 int somelongname = 2; 523 double c = 3; 524 525 int d = 3; 526 527 * ``bool AcrossComments`` Whether to align across comments. 528 529 .. code-block:: c++ 530 531 true: 532 int d = 3; 533 /* A comment. */ 534 double e = 4; 535 536 false: 537 int d = 3; 538 /* A comment. */ 539 double e = 4; 540 541 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 542 like ``+=`` are aligned along with ``=``. 543 544 .. code-block:: c++ 545 546 true: 547 a &= 2; 548 bbb = 2; 549 550 false: 551 a &= 2; 552 bbb = 2; 553 554 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 555 are aligned. 556 557 .. code-block:: c++ 558 559 true: 560 unsigned int f1(void); 561 void f2(void); 562 size_t f3(void); 563 564 false: 565 unsigned int f1(void); 566 void f2(void); 567 size_t f3(void); 568 569 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 570 aligned. 571 572 .. code-block:: c++ 573 574 true: 575 unsigned i; 576 int &r; 577 int *p; 578 int (*f)(); 579 580 false: 581 unsigned i; 582 int &r; 583 int *p; 584 int (*f)(); 585 586 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 587 operators are left-padded to the same length as long ones in order to 588 put all assignment operators to the right of the left hand side. 589 590 .. code-block:: c++ 591 592 true: 593 a >>= 2; 594 bbb = 2; 595 596 a = 2; 597 bbb >>= 2; 598 599 false: 600 a >>= 2; 601 bbb = 2; 602 603 a = 2; 604 bbb >>= 2; 605 606 607.. _AlignConsecutiveDeclarations: 608 609**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveDeclarations>` 610 Style of aligning consecutive declarations. 611 612 ``Consecutive`` will align the declaration names of consecutive lines. 613 This will result in formattings like: 614 615 .. code-block:: c++ 616 617 int aaaa = 12; 618 float b = 23; 619 std::string ccc; 620 621 Nested configuration flags: 622 623 Alignment options. 624 625 They can also be read as a whole for compatibility. The choices are: 626 627 * ``None`` 628 * ``Consecutive`` 629 * ``AcrossEmptyLines`` 630 * ``AcrossComments`` 631 * ``AcrossEmptyLinesAndComments`` 632 633 For example, to align across empty lines and not across comments, either 634 of these work. 635 636 .. code-block:: c++ 637 638 AlignConsecutiveDeclarations: AcrossEmptyLines 639 640 AlignConsecutiveDeclarations: 641 Enabled: true 642 AcrossEmptyLines: true 643 AcrossComments: false 644 645 * ``bool Enabled`` Whether aligning is enabled. 646 647 .. code-block:: c++ 648 649 #define SHORT_NAME 42 650 #define LONGER_NAME 0x007f 651 #define EVEN_LONGER_NAME (2) 652 #define foo(x) (x * x) 653 #define bar(y, z) (y + z) 654 655 int a = 1; 656 int somelongname = 2; 657 double c = 3; 658 659 int aaaa : 1; 660 int b : 12; 661 int ccc : 8; 662 663 int aaaa = 12; 664 float b = 23; 665 std::string ccc; 666 667 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 668 669 .. code-block:: c++ 670 671 true: 672 int a = 1; 673 int somelongname = 2; 674 double c = 3; 675 676 int d = 3; 677 678 false: 679 int a = 1; 680 int somelongname = 2; 681 double c = 3; 682 683 int d = 3; 684 685 * ``bool AcrossComments`` Whether to align across comments. 686 687 .. code-block:: c++ 688 689 true: 690 int d = 3; 691 /* A comment. */ 692 double e = 4; 693 694 false: 695 int d = 3; 696 /* A comment. */ 697 double e = 4; 698 699 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 700 like ``+=`` are aligned along with ``=``. 701 702 .. code-block:: c++ 703 704 true: 705 a &= 2; 706 bbb = 2; 707 708 false: 709 a &= 2; 710 bbb = 2; 711 712 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 713 are aligned. 714 715 .. code-block:: c++ 716 717 true: 718 unsigned int f1(void); 719 void f2(void); 720 size_t f3(void); 721 722 false: 723 unsigned int f1(void); 724 void f2(void); 725 size_t f3(void); 726 727 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 728 aligned. 729 730 .. code-block:: c++ 731 732 true: 733 unsigned i; 734 int &r; 735 int *p; 736 int (*f)(); 737 738 false: 739 unsigned i; 740 int &r; 741 int *p; 742 int (*f)(); 743 744 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 745 operators are left-padded to the same length as long ones in order to 746 put all assignment operators to the right of the left hand side. 747 748 .. code-block:: c++ 749 750 true: 751 a >>= 2; 752 bbb = 2; 753 754 a = 2; 755 bbb >>= 2; 756 757 false: 758 a >>= 2; 759 bbb = 2; 760 761 a = 2; 762 bbb >>= 2; 763 764 765.. _AlignConsecutiveMacros: 766 767**AlignConsecutiveMacros** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 9` :ref:`¶ <AlignConsecutiveMacros>` 768 Style of aligning consecutive macro definitions. 769 770 ``Consecutive`` will result in formattings like: 771 772 .. code-block:: c++ 773 774 #define SHORT_NAME 42 775 #define LONGER_NAME 0x007f 776 #define EVEN_LONGER_NAME (2) 777 #define foo(x) (x * x) 778 #define bar(y, z) (y + z) 779 780 Nested configuration flags: 781 782 Alignment options. 783 784 They can also be read as a whole for compatibility. The choices are: 785 786 * ``None`` 787 * ``Consecutive`` 788 * ``AcrossEmptyLines`` 789 * ``AcrossComments`` 790 * ``AcrossEmptyLinesAndComments`` 791 792 For example, to align across empty lines and not across comments, either 793 of these work. 794 795 .. code-block:: c++ 796 797 AlignConsecutiveMacros: AcrossEmptyLines 798 799 AlignConsecutiveMacros: 800 Enabled: true 801 AcrossEmptyLines: true 802 AcrossComments: false 803 804 * ``bool Enabled`` Whether aligning is enabled. 805 806 .. code-block:: c++ 807 808 #define SHORT_NAME 42 809 #define LONGER_NAME 0x007f 810 #define EVEN_LONGER_NAME (2) 811 #define foo(x) (x * x) 812 #define bar(y, z) (y + z) 813 814 int a = 1; 815 int somelongname = 2; 816 double c = 3; 817 818 int aaaa : 1; 819 int b : 12; 820 int ccc : 8; 821 822 int aaaa = 12; 823 float b = 23; 824 std::string ccc; 825 826 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 827 828 .. code-block:: c++ 829 830 true: 831 int a = 1; 832 int somelongname = 2; 833 double c = 3; 834 835 int d = 3; 836 837 false: 838 int a = 1; 839 int somelongname = 2; 840 double c = 3; 841 842 int d = 3; 843 844 * ``bool AcrossComments`` Whether to align across comments. 845 846 .. code-block:: c++ 847 848 true: 849 int d = 3; 850 /* A comment. */ 851 double e = 4; 852 853 false: 854 int d = 3; 855 /* A comment. */ 856 double e = 4; 857 858 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 859 like ``+=`` are aligned along with ``=``. 860 861 .. code-block:: c++ 862 863 true: 864 a &= 2; 865 bbb = 2; 866 867 false: 868 a &= 2; 869 bbb = 2; 870 871 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 872 are aligned. 873 874 .. code-block:: c++ 875 876 true: 877 unsigned int f1(void); 878 void f2(void); 879 size_t f3(void); 880 881 false: 882 unsigned int f1(void); 883 void f2(void); 884 size_t f3(void); 885 886 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 887 aligned. 888 889 .. code-block:: c++ 890 891 true: 892 unsigned i; 893 int &r; 894 int *p; 895 int (*f)(); 896 897 false: 898 unsigned i; 899 int &r; 900 int *p; 901 int (*f)(); 902 903 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 904 operators are left-padded to the same length as long ones in order to 905 put all assignment operators to the right of the left hand side. 906 907 .. code-block:: c++ 908 909 true: 910 a >>= 2; 911 bbb = 2; 912 913 a = 2; 914 bbb >>= 2; 915 916 false: 917 a >>= 2; 918 bbb = 2; 919 920 a = 2; 921 bbb >>= 2; 922 923 924.. _AlignConsecutiveShortCaseStatements: 925 926**AlignConsecutiveShortCaseStatements** (``ShortCaseStatementsAlignmentStyle``) :versionbadge:`clang-format 17` :ref:`¶ <AlignConsecutiveShortCaseStatements>` 927 Style of aligning consecutive short case labels. 928 Only applies if ``AllowShortCaseExpressionOnASingleLine`` or 929 ``AllowShortCaseLabelsOnASingleLine`` is ``true``. 930 931 932 .. code-block:: yaml 933 934 # Example of usage: 935 AlignConsecutiveShortCaseStatements: 936 Enabled: true 937 AcrossEmptyLines: true 938 AcrossComments: true 939 AlignCaseColons: false 940 941 Nested configuration flags: 942 943 Alignment options. 944 945 * ``bool Enabled`` Whether aligning is enabled. 946 947 .. code-block:: c++ 948 949 true: 950 switch (level) { 951 case log::info: return "info:"; 952 case log::warning: return "warning:"; 953 default: return ""; 954 } 955 956 false: 957 switch (level) { 958 case log::info: return "info:"; 959 case log::warning: return "warning:"; 960 default: return ""; 961 } 962 963 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 964 965 .. code-block:: c++ 966 967 true: 968 switch (level) { 969 case log::info: return "info:"; 970 case log::warning: return "warning:"; 971 972 default: return ""; 973 } 974 975 false: 976 switch (level) { 977 case log::info: return "info:"; 978 case log::warning: return "warning:"; 979 980 default: return ""; 981 } 982 983 * ``bool AcrossComments`` Whether to align across comments. 984 985 .. code-block:: c++ 986 987 true: 988 switch (level) { 989 case log::info: return "info:"; 990 case log::warning: return "warning:"; 991 /* A comment. */ 992 default: return ""; 993 } 994 995 false: 996 switch (level) { 997 case log::info: return "info:"; 998 case log::warning: return "warning:"; 999 /* A comment. */ 1000 default: return ""; 1001 } 1002 1003 * ``bool AlignCaseArrows`` Whether to align the case arrows when aligning short case expressions. 1004 1005 .. code-block:: java 1006 1007 true: 1008 i = switch (day) { 1009 case THURSDAY, SATURDAY -> 8; 1010 case WEDNESDAY -> 9; 1011 default -> 0; 1012 }; 1013 1014 false: 1015 i = switch (day) { 1016 case THURSDAY, SATURDAY -> 8; 1017 case WEDNESDAY -> 9; 1018 default -> 0; 1019 }; 1020 1021 * ``bool AlignCaseColons`` Whether aligned case labels are aligned on the colon, or on the tokens 1022 after the colon. 1023 1024 .. code-block:: c++ 1025 1026 true: 1027 switch (level) { 1028 case log::info : return "info:"; 1029 case log::warning: return "warning:"; 1030 default : return ""; 1031 } 1032 1033 false: 1034 switch (level) { 1035 case log::info: return "info:"; 1036 case log::warning: return "warning:"; 1037 default: return ""; 1038 } 1039 1040 1041.. _AlignConsecutiveTableGenBreakingDAGArgColons: 1042 1043**AlignConsecutiveTableGenBreakingDAGArgColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenBreakingDAGArgColons>` 1044 Style of aligning consecutive TableGen DAGArg operator colons. 1045 If enabled, align the colon inside DAGArg which have line break inside. 1046 This works only when TableGenBreakInsideDAGArg is BreakElements or 1047 BreakAll and the DAGArg is not excepted by 1048 TableGenBreakingDAGArgOperators's effect. 1049 1050 .. code-block:: c++ 1051 1052 let dagarg = (ins 1053 a :$src1, 1054 aa :$src2, 1055 aaa:$src3 1056 ) 1057 1058 Nested configuration flags: 1059 1060 Alignment options. 1061 1062 They can also be read as a whole for compatibility. The choices are: 1063 1064 * ``None`` 1065 * ``Consecutive`` 1066 * ``AcrossEmptyLines`` 1067 * ``AcrossComments`` 1068 * ``AcrossEmptyLinesAndComments`` 1069 1070 For example, to align across empty lines and not across comments, either 1071 of these work. 1072 1073 .. code-block:: c++ 1074 1075 AlignConsecutiveTableGenBreakingDAGArgColons: AcrossEmptyLines 1076 1077 AlignConsecutiveTableGenBreakingDAGArgColons: 1078 Enabled: true 1079 AcrossEmptyLines: true 1080 AcrossComments: false 1081 1082 * ``bool Enabled`` Whether aligning is enabled. 1083 1084 .. code-block:: c++ 1085 1086 #define SHORT_NAME 42 1087 #define LONGER_NAME 0x007f 1088 #define EVEN_LONGER_NAME (2) 1089 #define foo(x) (x * x) 1090 #define bar(y, z) (y + z) 1091 1092 int a = 1; 1093 int somelongname = 2; 1094 double c = 3; 1095 1096 int aaaa : 1; 1097 int b : 12; 1098 int ccc : 8; 1099 1100 int aaaa = 12; 1101 float b = 23; 1102 std::string ccc; 1103 1104 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 1105 1106 .. code-block:: c++ 1107 1108 true: 1109 int a = 1; 1110 int somelongname = 2; 1111 double c = 3; 1112 1113 int d = 3; 1114 1115 false: 1116 int a = 1; 1117 int somelongname = 2; 1118 double c = 3; 1119 1120 int d = 3; 1121 1122 * ``bool AcrossComments`` Whether to align across comments. 1123 1124 .. code-block:: c++ 1125 1126 true: 1127 int d = 3; 1128 /* A comment. */ 1129 double e = 4; 1130 1131 false: 1132 int d = 3; 1133 /* A comment. */ 1134 double e = 4; 1135 1136 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 1137 like ``+=`` are aligned along with ``=``. 1138 1139 .. code-block:: c++ 1140 1141 true: 1142 a &= 2; 1143 bbb = 2; 1144 1145 false: 1146 a &= 2; 1147 bbb = 2; 1148 1149 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 1150 are aligned. 1151 1152 .. code-block:: c++ 1153 1154 true: 1155 unsigned int f1(void); 1156 void f2(void); 1157 size_t f3(void); 1158 1159 false: 1160 unsigned int f1(void); 1161 void f2(void); 1162 size_t f3(void); 1163 1164 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 1165 aligned. 1166 1167 .. code-block:: c++ 1168 1169 true: 1170 unsigned i; 1171 int &r; 1172 int *p; 1173 int (*f)(); 1174 1175 false: 1176 unsigned i; 1177 int &r; 1178 int *p; 1179 int (*f)(); 1180 1181 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 1182 operators are left-padded to the same length as long ones in order to 1183 put all assignment operators to the right of the left hand side. 1184 1185 .. code-block:: c++ 1186 1187 true: 1188 a >>= 2; 1189 bbb = 2; 1190 1191 a = 2; 1192 bbb >>= 2; 1193 1194 false: 1195 a >>= 2; 1196 bbb = 2; 1197 1198 a = 2; 1199 bbb >>= 2; 1200 1201 1202.. _AlignConsecutiveTableGenCondOperatorColons: 1203 1204**AlignConsecutiveTableGenCondOperatorColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenCondOperatorColons>` 1205 Style of aligning consecutive TableGen cond operator colons. 1206 Align the colons of cases inside !cond operators. 1207 1208 .. code-block:: c++ 1209 1210 !cond(!eq(size, 1) : 1, 1211 !eq(size, 16): 1, 1212 true : 0) 1213 1214 Nested configuration flags: 1215 1216 Alignment options. 1217 1218 They can also be read as a whole for compatibility. The choices are: 1219 1220 * ``None`` 1221 * ``Consecutive`` 1222 * ``AcrossEmptyLines`` 1223 * ``AcrossComments`` 1224 * ``AcrossEmptyLinesAndComments`` 1225 1226 For example, to align across empty lines and not across comments, either 1227 of these work. 1228 1229 .. code-block:: c++ 1230 1231 AlignConsecutiveTableGenCondOperatorColons: AcrossEmptyLines 1232 1233 AlignConsecutiveTableGenCondOperatorColons: 1234 Enabled: true 1235 AcrossEmptyLines: true 1236 AcrossComments: false 1237 1238 * ``bool Enabled`` Whether aligning is enabled. 1239 1240 .. code-block:: c++ 1241 1242 #define SHORT_NAME 42 1243 #define LONGER_NAME 0x007f 1244 #define EVEN_LONGER_NAME (2) 1245 #define foo(x) (x * x) 1246 #define bar(y, z) (y + z) 1247 1248 int a = 1; 1249 int somelongname = 2; 1250 double c = 3; 1251 1252 int aaaa : 1; 1253 int b : 12; 1254 int ccc : 8; 1255 1256 int aaaa = 12; 1257 float b = 23; 1258 std::string ccc; 1259 1260 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 1261 1262 .. code-block:: c++ 1263 1264 true: 1265 int a = 1; 1266 int somelongname = 2; 1267 double c = 3; 1268 1269 int d = 3; 1270 1271 false: 1272 int a = 1; 1273 int somelongname = 2; 1274 double c = 3; 1275 1276 int d = 3; 1277 1278 * ``bool AcrossComments`` Whether to align across comments. 1279 1280 .. code-block:: c++ 1281 1282 true: 1283 int d = 3; 1284 /* A comment. */ 1285 double e = 4; 1286 1287 false: 1288 int d = 3; 1289 /* A comment. */ 1290 double e = 4; 1291 1292 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 1293 like ``+=`` are aligned along with ``=``. 1294 1295 .. code-block:: c++ 1296 1297 true: 1298 a &= 2; 1299 bbb = 2; 1300 1301 false: 1302 a &= 2; 1303 bbb = 2; 1304 1305 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 1306 are aligned. 1307 1308 .. code-block:: c++ 1309 1310 true: 1311 unsigned int f1(void); 1312 void f2(void); 1313 size_t f3(void); 1314 1315 false: 1316 unsigned int f1(void); 1317 void f2(void); 1318 size_t f3(void); 1319 1320 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 1321 aligned. 1322 1323 .. code-block:: c++ 1324 1325 true: 1326 unsigned i; 1327 int &r; 1328 int *p; 1329 int (*f)(); 1330 1331 false: 1332 unsigned i; 1333 int &r; 1334 int *p; 1335 int (*f)(); 1336 1337 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 1338 operators are left-padded to the same length as long ones in order to 1339 put all assignment operators to the right of the left hand side. 1340 1341 .. code-block:: c++ 1342 1343 true: 1344 a >>= 2; 1345 bbb = 2; 1346 1347 a = 2; 1348 bbb >>= 2; 1349 1350 false: 1351 a >>= 2; 1352 bbb = 2; 1353 1354 a = 2; 1355 bbb >>= 2; 1356 1357 1358.. _AlignConsecutiveTableGenDefinitionColons: 1359 1360**AlignConsecutiveTableGenDefinitionColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenDefinitionColons>` 1361 Style of aligning consecutive TableGen definition colons. 1362 This aligns the inheritance colons of consecutive definitions. 1363 1364 .. code-block:: c++ 1365 1366 def Def : Parent {} 1367 def DefDef : Parent {} 1368 def DefDefDef : Parent {} 1369 1370 Nested configuration flags: 1371 1372 Alignment options. 1373 1374 They can also be read as a whole for compatibility. The choices are: 1375 1376 * ``None`` 1377 * ``Consecutive`` 1378 * ``AcrossEmptyLines`` 1379 * ``AcrossComments`` 1380 * ``AcrossEmptyLinesAndComments`` 1381 1382 For example, to align across empty lines and not across comments, either 1383 of these work. 1384 1385 .. code-block:: c++ 1386 1387 AlignConsecutiveTableGenDefinitionColons: AcrossEmptyLines 1388 1389 AlignConsecutiveTableGenDefinitionColons: 1390 Enabled: true 1391 AcrossEmptyLines: true 1392 AcrossComments: false 1393 1394 * ``bool Enabled`` Whether aligning is enabled. 1395 1396 .. code-block:: c++ 1397 1398 #define SHORT_NAME 42 1399 #define LONGER_NAME 0x007f 1400 #define EVEN_LONGER_NAME (2) 1401 #define foo(x) (x * x) 1402 #define bar(y, z) (y + z) 1403 1404 int a = 1; 1405 int somelongname = 2; 1406 double c = 3; 1407 1408 int aaaa : 1; 1409 int b : 12; 1410 int ccc : 8; 1411 1412 int aaaa = 12; 1413 float b = 23; 1414 std::string ccc; 1415 1416 * ``bool AcrossEmptyLines`` Whether to align across empty lines. 1417 1418 .. code-block:: c++ 1419 1420 true: 1421 int a = 1; 1422 int somelongname = 2; 1423 double c = 3; 1424 1425 int d = 3; 1426 1427 false: 1428 int a = 1; 1429 int somelongname = 2; 1430 double c = 3; 1431 1432 int d = 3; 1433 1434 * ``bool AcrossComments`` Whether to align across comments. 1435 1436 .. code-block:: c++ 1437 1438 true: 1439 int d = 3; 1440 /* A comment. */ 1441 double e = 4; 1442 1443 false: 1444 int d = 3; 1445 /* A comment. */ 1446 double e = 4; 1447 1448 * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments 1449 like ``+=`` are aligned along with ``=``. 1450 1451 .. code-block:: c++ 1452 1453 true: 1454 a &= 2; 1455 bbb = 2; 1456 1457 false: 1458 a &= 2; 1459 bbb = 2; 1460 1461 * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations 1462 are aligned. 1463 1464 .. code-block:: c++ 1465 1466 true: 1467 unsigned int f1(void); 1468 void f2(void); 1469 size_t f3(void); 1470 1471 false: 1472 unsigned int f1(void); 1473 void f2(void); 1474 size_t f3(void); 1475 1476 * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are 1477 aligned. 1478 1479 .. code-block:: c++ 1480 1481 true: 1482 unsigned i; 1483 int &r; 1484 int *p; 1485 int (*f)(); 1486 1487 false: 1488 unsigned i; 1489 int &r; 1490 int *p; 1491 int (*f)(); 1492 1493 * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment 1494 operators are left-padded to the same length as long ones in order to 1495 put all assignment operators to the right of the left hand side. 1496 1497 .. code-block:: c++ 1498 1499 true: 1500 a >>= 2; 1501 bbb = 2; 1502 1503 a = 2; 1504 bbb >>= 2; 1505 1506 false: 1507 a >>= 2; 1508 bbb = 2; 1509 1510 a = 2; 1511 bbb >>= 2; 1512 1513 1514.. _AlignEscapedNewlines: 1515 1516**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) :versionbadge:`clang-format 5` :ref:`¶ <AlignEscapedNewlines>` 1517 Options for aligning backslashes in escaped newlines. 1518 1519 Possible values: 1520 1521 * ``ENAS_DontAlign`` (in configuration: ``DontAlign``) 1522 Don't align escaped newlines. 1523 1524 .. code-block:: c++ 1525 1526 #define A \ 1527 int aaaa; \ 1528 int b; \ 1529 int dddddddddd; 1530 1531 * ``ENAS_Left`` (in configuration: ``Left``) 1532 Align escaped newlines as far left as possible. 1533 1534 .. code-block:: c++ 1535 1536 #define A \ 1537 int aaaa; \ 1538 int b; \ 1539 int dddddddddd; 1540 1541 * ``ENAS_LeftWithLastLine`` (in configuration: ``LeftWithLastLine``) 1542 Align escaped newlines as far left as possible, using the last line of 1543 the preprocessor directive as the reference if it's the longest. 1544 1545 .. code-block:: c++ 1546 1547 #define A \ 1548 int aaaa; \ 1549 int b; \ 1550 int dddddddddd; 1551 1552 * ``ENAS_Right`` (in configuration: ``Right``) 1553 Align escaped newlines in the right-most column. 1554 1555 .. code-block:: c++ 1556 1557 #define A \ 1558 int aaaa; \ 1559 int b; \ 1560 int dddddddddd; 1561 1562 1563 1564.. _AlignOperands: 1565 1566**AlignOperands** (``OperandAlignmentStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AlignOperands>` 1567 If ``true``, horizontally align operands of binary and ternary 1568 expressions. 1569 1570 Possible values: 1571 1572 * ``OAS_DontAlign`` (in configuration: ``DontAlign``) 1573 Do not align operands of binary and ternary expressions. 1574 The wrapped lines are indented ``ContinuationIndentWidth`` spaces from 1575 the start of the line. 1576 1577 * ``OAS_Align`` (in configuration: ``Align``) 1578 Horizontally align operands of binary and ternary expressions. 1579 1580 Specifically, this aligns operands of a single expression that needs 1581 to be split over multiple lines, e.g.: 1582 1583 .. code-block:: c++ 1584 1585 int aaa = bbbbbbbbbbbbbbb + 1586 ccccccccccccccc; 1587 1588 When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is 1589 aligned with the operand on the first line. 1590 1591 .. code-block:: c++ 1592 1593 int aaa = bbbbbbbbbbbbbbb 1594 + ccccccccccccccc; 1595 1596 * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``) 1597 Horizontally align operands of binary and ternary expressions. 1598 1599 This is similar to ``OAS_Align``, except when 1600 ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so 1601 that the wrapped operand is aligned with the operand on the first line. 1602 1603 .. code-block:: c++ 1604 1605 int aaa = bbbbbbbbbbbbbbb 1606 + ccccccccccccccc; 1607 1608 1609 1610.. _AlignTrailingComments: 1611 1612**AlignTrailingComments** (``TrailingCommentsAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlignTrailingComments>` 1613 Control of trailing comments. 1614 1615 The alignment stops at closing braces after a line break, and only 1616 followed by other closing braces, a (``do-``) ``while``, a lambda call, or 1617 a semicolon. 1618 1619 1620 .. note:: 1621 1622 As of clang-format 16 this option is not a bool but can be set 1623 to the options. Conventional bool options still can be parsed as before. 1624 1625 1626 .. code-block:: yaml 1627 1628 # Example of usage: 1629 AlignTrailingComments: 1630 Kind: Always 1631 OverEmptyLines: 2 1632 1633 Nested configuration flags: 1634 1635 Alignment options 1636 1637 * ``TrailingCommentsAlignmentKinds Kind`` 1638 Specifies the way to align trailing comments. 1639 1640 Possible values: 1641 1642 * ``TCAS_Leave`` (in configuration: ``Leave``) 1643 Leave trailing comments as they are. 1644 1645 .. code-block:: c++ 1646 1647 int a; // comment 1648 int ab; // comment 1649 1650 int abc; // comment 1651 int abcd; // comment 1652 1653 * ``TCAS_Always`` (in configuration: ``Always``) 1654 Align trailing comments. 1655 1656 .. code-block:: c++ 1657 1658 int a; // comment 1659 int ab; // comment 1660 1661 int abc; // comment 1662 int abcd; // comment 1663 1664 * ``TCAS_Never`` (in configuration: ``Never``) 1665 Don't align trailing comments but other formatter applies. 1666 1667 .. code-block:: c++ 1668 1669 int a; // comment 1670 int ab; // comment 1671 1672 int abc; // comment 1673 int abcd; // comment 1674 1675 1676 * ``unsigned OverEmptyLines`` How many empty lines to apply alignment. 1677 When both ``MaxEmptyLinesToKeep`` and ``OverEmptyLines`` are set to 2, 1678 it formats like below. 1679 1680 .. code-block:: c++ 1681 1682 int a; // all these 1683 1684 int ab; // comments are 1685 1686 1687 int abcdef; // aligned 1688 1689 When ``MaxEmptyLinesToKeep`` is set to 2 and ``OverEmptyLines`` is set 1690 to 1, it formats like below. 1691 1692 .. code-block:: c++ 1693 1694 int a; // these are 1695 1696 int ab; // aligned 1697 1698 1699 int abcdef; // but this isn't 1700 1701 1702.. _AllowAllArgumentsOnNextLine: 1703 1704**AllowAllArgumentsOnNextLine** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <AllowAllArgumentsOnNextLine>` 1705 If a function call or braced initializer list doesn't fit on a 1706 line, allow putting all arguments onto the next line, even if 1707 ``BinPackArguments`` is ``false``. 1708 1709 .. code-block:: c++ 1710 1711 true: 1712 callFunction( 1713 a, b, c, d); 1714 1715 false: 1716 callFunction(a, 1717 b, 1718 c, 1719 d); 1720 1721.. _AllowAllConstructorInitializersOnNextLine: 1722 1723**AllowAllConstructorInitializersOnNextLine** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <AllowAllConstructorInitializersOnNextLine>` 1724 This option is **deprecated**. See ``NextLine`` of 1725 ``PackConstructorInitializers``. 1726 1727.. _AllowAllParametersOfDeclarationOnNextLine: 1728 1729**AllowAllParametersOfDeclarationOnNextLine** (``Boolean``) :versionbadge:`clang-format 3.3` :ref:`¶ <AllowAllParametersOfDeclarationOnNextLine>` 1730 If the function declaration doesn't fit on a line, 1731 allow putting all parameters of a function declaration onto 1732 the next line even if ``BinPackParameters`` is ``OnePerLine``. 1733 1734 .. code-block:: c++ 1735 1736 true: 1737 void myFunction( 1738 int a, int b, int c, int d, int e); 1739 1740 false: 1741 void myFunction(int a, 1742 int b, 1743 int c, 1744 int d, 1745 int e); 1746 1747.. _AllowBreakBeforeNoexceptSpecifier: 1748 1749**AllowBreakBeforeNoexceptSpecifier** (``BreakBeforeNoexceptSpecifierStyle``) :versionbadge:`clang-format 18` :ref:`¶ <AllowBreakBeforeNoexceptSpecifier>` 1750 Controls if there could be a line break before a ``noexcept`` specifier. 1751 1752 Possible values: 1753 1754 * ``BBNSS_Never`` (in configuration: ``Never``) 1755 No line break allowed. 1756 1757 .. code-block:: c++ 1758 1759 void foo(int arg1, 1760 double arg2) noexcept; 1761 1762 void bar(int arg1, double arg2) noexcept( 1763 noexcept(baz(arg1)) && 1764 noexcept(baz(arg2))); 1765 1766 * ``BBNSS_OnlyWithParen`` (in configuration: ``OnlyWithParen``) 1767 For a simple ``noexcept`` there is no line break allowed, but when we 1768 have a condition it is. 1769 1770 .. code-block:: c++ 1771 1772 void foo(int arg1, 1773 double arg2) noexcept; 1774 1775 void bar(int arg1, double arg2) 1776 noexcept(noexcept(baz(arg1)) && 1777 noexcept(baz(arg2))); 1778 1779 * ``BBNSS_Always`` (in configuration: ``Always``) 1780 Line breaks are allowed. But note that because of the associated 1781 penalties ``clang-format`` often prefers not to break before the 1782 ``noexcept``. 1783 1784 .. code-block:: c++ 1785 1786 void foo(int arg1, 1787 double arg2) noexcept; 1788 1789 void bar(int arg1, double arg2) 1790 noexcept(noexcept(baz(arg1)) && 1791 noexcept(baz(arg2))); 1792 1793 1794 1795.. _AllowShortBlocksOnASingleLine: 1796 1797**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AllowShortBlocksOnASingleLine>` 1798 Dependent on the value, ``while (true) { continue; }`` can be put on a 1799 single line. 1800 1801 Possible values: 1802 1803 * ``SBS_Never`` (in configuration: ``Never``) 1804 Never merge blocks into a single line. 1805 1806 .. code-block:: c++ 1807 1808 while (true) { 1809 } 1810 while (true) { 1811 continue; 1812 } 1813 1814 * ``SBS_Empty`` (in configuration: ``Empty``) 1815 Only merge empty blocks. 1816 1817 .. code-block:: c++ 1818 1819 while (true) {} 1820 while (true) { 1821 continue; 1822 } 1823 1824 * ``SBS_Always`` (in configuration: ``Always``) 1825 Always merge short blocks into a single line. 1826 1827 .. code-block:: c++ 1828 1829 while (true) {} 1830 while (true) { continue; } 1831 1832 1833 1834.. _AllowShortCaseExpressionOnASingleLine: 1835 1836**AllowShortCaseExpressionOnASingleLine** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <AllowShortCaseExpressionOnASingleLine>` 1837 Whether to merge a short switch labeled rule into a single line. 1838 1839 .. code-block:: java 1840 1841 true: false: 1842 switch (a) { vs. switch (a) { 1843 case 1 -> 1; case 1 -> 1844 default -> 0; 1; 1845 }; default -> 1846 0; 1847 }; 1848 1849.. _AllowShortCaseLabelsOnASingleLine: 1850 1851**AllowShortCaseLabelsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.6` :ref:`¶ <AllowShortCaseLabelsOnASingleLine>` 1852 If ``true``, short case labels will be contracted to a single line. 1853 1854 .. code-block:: c++ 1855 1856 true: false: 1857 switch (a) { vs. switch (a) { 1858 case 1: x = 1; break; case 1: 1859 case 2: return; x = 1; 1860 } break; 1861 case 2: 1862 return; 1863 } 1864 1865.. _AllowShortCompoundRequirementOnASingleLine: 1866 1867**AllowShortCompoundRequirementOnASingleLine** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <AllowShortCompoundRequirementOnASingleLine>` 1868 Allow short compound requirement on a single line. 1869 1870 .. code-block:: c++ 1871 1872 true: 1873 template <typename T> 1874 concept c = requires(T x) { 1875 { x + 1 } -> std::same_as<int>; 1876 }; 1877 1878 false: 1879 template <typename T> 1880 concept c = requires(T x) { 1881 { 1882 x + 1 1883 } -> std::same_as<int>; 1884 }; 1885 1886.. _AllowShortEnumsOnASingleLine: 1887 1888**AllowShortEnumsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <AllowShortEnumsOnASingleLine>` 1889 Allow short enums on a single line. 1890 1891 .. code-block:: c++ 1892 1893 true: 1894 enum { A, B } myEnum; 1895 1896 false: 1897 enum { 1898 A, 1899 B 1900 } myEnum; 1901 1902.. _AllowShortFunctionsOnASingleLine: 1903 1904**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AllowShortFunctionsOnASingleLine>` 1905 Dependent on the value, ``int f() { return 0; }`` can be put on a 1906 single line. 1907 1908 Possible values: 1909 1910 * ``SFS_None`` (in configuration: ``None``) 1911 Never merge functions into a single line. 1912 1913 * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) 1914 Only merge functions defined inside a class. Same as ``inline``, 1915 except it does not implies ``empty``: i.e. top level empty functions 1916 are not merged either. 1917 1918 .. code-block:: c++ 1919 1920 class Foo { 1921 void f() { foo(); } 1922 }; 1923 void f() { 1924 foo(); 1925 } 1926 void f() { 1927 } 1928 1929 * ``SFS_Empty`` (in configuration: ``Empty``) 1930 Only merge empty functions. 1931 1932 .. code-block:: c++ 1933 1934 void f() {} 1935 void f2() { 1936 bar2(); 1937 } 1938 1939 * ``SFS_Inline`` (in configuration: ``Inline``) 1940 Only merge functions defined inside a class. Implies ``empty``. 1941 1942 .. code-block:: c++ 1943 1944 class Foo { 1945 void f() { foo(); } 1946 }; 1947 void f() { 1948 foo(); 1949 } 1950 void f() {} 1951 1952 * ``SFS_All`` (in configuration: ``All``) 1953 Merge all functions fitting on a single line. 1954 1955 .. code-block:: c++ 1956 1957 class Foo { 1958 void f() { foo(); } 1959 }; 1960 void f() { bar(); } 1961 1962 1963 1964.. _AllowShortIfStatementsOnASingleLine: 1965 1966**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) :versionbadge:`clang-format 3.3` :ref:`¶ <AllowShortIfStatementsOnASingleLine>` 1967 Dependent on the value, ``if (a) return;`` can be put on a single line. 1968 1969 Possible values: 1970 1971 * ``SIS_Never`` (in configuration: ``Never``) 1972 Never put short ifs on the same line. 1973 1974 .. code-block:: c++ 1975 1976 if (a) 1977 return; 1978 1979 if (b) 1980 return; 1981 else 1982 return; 1983 1984 if (c) 1985 return; 1986 else { 1987 return; 1988 } 1989 1990 * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``) 1991 Put short ifs on the same line only if there is no else statement. 1992 1993 .. code-block:: c++ 1994 1995 if (a) return; 1996 1997 if (b) 1998 return; 1999 else 2000 return; 2001 2002 if (c) 2003 return; 2004 else { 2005 return; 2006 } 2007 2008 * ``SIS_OnlyFirstIf`` (in configuration: ``OnlyFirstIf``) 2009 Put short ifs, but not else ifs nor else statements, on the same line. 2010 2011 .. code-block:: c++ 2012 2013 if (a) return; 2014 2015 if (b) return; 2016 else if (b) 2017 return; 2018 else 2019 return; 2020 2021 if (c) return; 2022 else { 2023 return; 2024 } 2025 2026 * ``SIS_AllIfsAndElse`` (in configuration: ``AllIfsAndElse``) 2027 Always put short ifs, else ifs and else statements on the same 2028 line. 2029 2030 .. code-block:: c++ 2031 2032 if (a) return; 2033 2034 if (b) return; 2035 else return; 2036 2037 if (c) return; 2038 else { 2039 return; 2040 } 2041 2042 2043 2044.. _AllowShortLambdasOnASingleLine: 2045 2046**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) :versionbadge:`clang-format 9` :ref:`¶ <AllowShortLambdasOnASingleLine>` 2047 Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a 2048 single line. 2049 2050 Possible values: 2051 2052 * ``SLS_None`` (in configuration: ``None``) 2053 Never merge lambdas into a single line. 2054 2055 * ``SLS_Empty`` (in configuration: ``Empty``) 2056 Only merge empty lambdas. 2057 2058 .. code-block:: c++ 2059 2060 auto lambda = [](int a) {}; 2061 auto lambda2 = [](int a) { 2062 return a; 2063 }; 2064 2065 * ``SLS_Inline`` (in configuration: ``Inline``) 2066 Merge lambda into a single line if the lambda is argument of a function. 2067 2068 .. code-block:: c++ 2069 2070 auto lambda = [](int x, int y) { 2071 return x < y; 2072 }; 2073 sort(a.begin(), a.end(), [](int x, int y) { return x < y; }); 2074 2075 * ``SLS_All`` (in configuration: ``All``) 2076 Merge all lambdas fitting on a single line. 2077 2078 .. code-block:: c++ 2079 2080 auto lambda = [](int a) {}; 2081 auto lambda2 = [](int a) { return a; }; 2082 2083 2084 2085.. _AllowShortLoopsOnASingleLine: 2086 2087**AllowShortLoopsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <AllowShortLoopsOnASingleLine>` 2088 If ``true``, ``while (true) continue;`` can be put on a single 2089 line. 2090 2091.. _AllowShortNamespacesOnASingleLine: 2092 2093**AllowShortNamespacesOnASingleLine** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <AllowShortNamespacesOnASingleLine>` 2094 If ``true``, ``namespace a { class b; }`` can be put on a single line. 2095 2096.. _AlwaysBreakAfterDefinitionReturnType: 2097 2098**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlwaysBreakAfterDefinitionReturnType>` 2099 The function definition return type breaking style to use. This 2100 option is **deprecated** and is retained for backwards compatibility. 2101 2102 Possible values: 2103 2104 * ``DRTBS_None`` (in configuration: ``None``) 2105 Break after return type automatically. 2106 ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. 2107 2108 * ``DRTBS_All`` (in configuration: ``All``) 2109 Always break after the return type. 2110 2111 * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) 2112 Always break after the return types of top-level functions. 2113 2114 2115 2116.. _AlwaysBreakAfterReturnType: 2117 2118**AlwaysBreakAfterReturnType** (``deprecated``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlwaysBreakAfterReturnType>` 2119 This option is renamed to ``BreakAfterReturnType``. 2120 2121.. _AlwaysBreakBeforeMultilineStrings: 2122 2123**AlwaysBreakBeforeMultilineStrings** (``Boolean``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakBeforeMultilineStrings>` 2124 If ``true``, always break before multiline string literals. 2125 2126 This flag is mean to make cases where there are multiple multiline strings 2127 in a file look more consistent. Thus, it will only take effect if wrapping 2128 the string at that point leads to it being indented 2129 ``ContinuationIndentWidth`` spaces from the start of the line. 2130 2131 .. code-block:: c++ 2132 2133 true: false: 2134 aaaa = vs. aaaa = "bbbb" 2135 "bbbb" "cccc"; 2136 "cccc"; 2137 2138.. _AlwaysBreakTemplateDeclarations: 2139 2140**AlwaysBreakTemplateDeclarations** (``deprecated``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakTemplateDeclarations>` 2141 This option is renamed to ``BreakTemplateDeclarations``. 2142 2143.. _AttributeMacros: 2144 2145**AttributeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <AttributeMacros>` 2146 A vector of strings that should be interpreted as attributes/qualifiers 2147 instead of identifiers. This can be useful for language extensions or 2148 static analyzer annotations. 2149 2150 For example: 2151 2152 .. code-block:: c++ 2153 2154 x = (char *__capability)&y; 2155 int function(void) __unused; 2156 void only_writes_to_buffer(char *__output buffer); 2157 2158 In the .clang-format configuration file, this can be configured like: 2159 2160 .. code-block:: yaml 2161 2162 AttributeMacros: [__capability, __output, __unused] 2163 2164.. _BinPackArguments: 2165 2166**BinPackArguments** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackArguments>` 2167 If ``false``, a function call's arguments will either be all on the 2168 same line or will have one line each. 2169 2170 .. code-block:: c++ 2171 2172 true: 2173 void f() { 2174 f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, 2175 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 2176 } 2177 2178 false: 2179 void f() { 2180 f(aaaaaaaaaaaaaaaaaaaa, 2181 aaaaaaaaaaaaaaaaaaaa, 2182 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); 2183 } 2184 2185.. _BinPackParameters: 2186 2187**BinPackParameters** (``BinPackParametersStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackParameters>` 2188 The bin pack parameters style to use. 2189 2190 Possible values: 2191 2192 * ``BPPS_BinPack`` (in configuration: ``BinPack``) 2193 Bin-pack parameters. 2194 2195 .. code-block:: c++ 2196 2197 void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb, 2198 int ccccccccccccccccccccccccccccccccccccccccccc); 2199 2200 * ``BPPS_OnePerLine`` (in configuration: ``OnePerLine``) 2201 Put all parameters on the current line if they fit. 2202 Otherwise, put each one on its own line. 2203 2204 .. code-block:: c++ 2205 2206 void f(int a, int b, int c); 2207 2208 void f(int a, 2209 int b, 2210 int ccccccccccccccccccccccccccccccccccccc); 2211 2212 * ``BPPS_AlwaysOnePerLine`` (in configuration: ``AlwaysOnePerLine``) 2213 Always put each parameter on its own line. 2214 2215 .. code-block:: c++ 2216 2217 void f(int a, 2218 int b, 2219 int c); 2220 2221 2222 2223.. _BitFieldColonSpacing: 2224 2225**BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BitFieldColonSpacing>` 2226 The BitFieldColonSpacingStyle to use for bitfields. 2227 2228 Possible values: 2229 2230 * ``BFCS_Both`` (in configuration: ``Both``) 2231 Add one space on each side of the ``:`` 2232 2233 .. code-block:: c++ 2234 2235 unsigned bf : 2; 2236 2237 * ``BFCS_None`` (in configuration: ``None``) 2238 Add no space around the ``:`` (except when needed for 2239 ``AlignConsecutiveBitFields``). 2240 2241 .. code-block:: c++ 2242 2243 unsigned bf:2; 2244 2245 * ``BFCS_Before`` (in configuration: ``Before``) 2246 Add space before the ``:`` only 2247 2248 .. code-block:: c++ 2249 2250 unsigned bf :2; 2251 2252 * ``BFCS_After`` (in configuration: ``After``) 2253 Add space after the ``:`` only (space may be added before if 2254 needed for ``AlignConsecutiveBitFields``). 2255 2256 .. code-block:: c++ 2257 2258 unsigned bf: 2; 2259 2260 2261 2262.. _BraceWrapping: 2263 2264**BraceWrapping** (``BraceWrappingFlags``) :versionbadge:`clang-format 3.8` :ref:`¶ <BraceWrapping>` 2265 Control of individual brace wrapping cases. 2266 2267 If ``BreakBeforeBraces`` is set to ``Custom``, use this to specify how 2268 each individual brace case should be handled. Otherwise, this is ignored. 2269 2270 .. code-block:: yaml 2271 2272 # Example of usage: 2273 BreakBeforeBraces: Custom 2274 BraceWrapping: 2275 AfterEnum: true 2276 AfterStruct: false 2277 SplitEmptyFunction: false 2278 2279 Nested configuration flags: 2280 2281 Precise control over the wrapping of braces. 2282 2283 .. code-block:: c++ 2284 2285 # Should be declared this way: 2286 BreakBeforeBraces: Custom 2287 BraceWrapping: 2288 AfterClass: true 2289 2290 * ``bool AfterCaseLabel`` Wrap case labels. 2291 2292 .. code-block:: c++ 2293 2294 false: true: 2295 switch (foo) { vs. switch (foo) { 2296 case 1: { case 1: 2297 bar(); { 2298 break; bar(); 2299 } break; 2300 default: { } 2301 plop(); default: 2302 } { 2303 } plop(); 2304 } 2305 } 2306 2307 * ``bool AfterClass`` Wrap class definitions. 2308 2309 .. code-block:: c++ 2310 2311 true: 2312 class foo 2313 {}; 2314 2315 false: 2316 class foo {}; 2317 2318 * ``BraceWrappingAfterControlStatementStyle AfterControlStatement`` 2319 Wrap control statements (``if``/``for``/``while``/``switch``/..). 2320 2321 Possible values: 2322 2323 * ``BWACS_Never`` (in configuration: ``Never``) 2324 Never wrap braces after a control statement. 2325 2326 .. code-block:: c++ 2327 2328 if (foo()) { 2329 } else { 2330 } 2331 for (int i = 0; i < 10; ++i) { 2332 } 2333 2334 * ``BWACS_MultiLine`` (in configuration: ``MultiLine``) 2335 Only wrap braces after a multi-line control statement. 2336 2337 .. code-block:: c++ 2338 2339 if (foo && bar && 2340 baz) 2341 { 2342 quux(); 2343 } 2344 while (foo || bar) { 2345 } 2346 2347 * ``BWACS_Always`` (in configuration: ``Always``) 2348 Always wrap braces after a control statement. 2349 2350 .. code-block:: c++ 2351 2352 if (foo()) 2353 { 2354 } else 2355 {} 2356 for (int i = 0; i < 10; ++i) 2357 {} 2358 2359 2360 * ``bool AfterEnum`` Wrap enum definitions. 2361 2362 .. code-block:: c++ 2363 2364 true: 2365 enum X : int 2366 { 2367 B 2368 }; 2369 2370 false: 2371 enum X : int { B }; 2372 2373 * ``bool AfterFunction`` Wrap function definitions. 2374 2375 .. code-block:: c++ 2376 2377 true: 2378 void foo() 2379 { 2380 bar(); 2381 bar2(); 2382 } 2383 2384 false: 2385 void foo() { 2386 bar(); 2387 bar2(); 2388 } 2389 2390 * ``bool AfterNamespace`` Wrap namespace definitions. 2391 2392 .. code-block:: c++ 2393 2394 true: 2395 namespace 2396 { 2397 int foo(); 2398 int bar(); 2399 } 2400 2401 false: 2402 namespace { 2403 int foo(); 2404 int bar(); 2405 } 2406 2407 * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...). 2408 2409 .. note:: 2410 2411 @autoreleasepool and @synchronized blocks are wrapped 2412 according to ``AfterControlStatement`` flag. 2413 2414 * ``bool AfterStruct`` Wrap struct definitions. 2415 2416 .. code-block:: c++ 2417 2418 true: 2419 struct foo 2420 { 2421 int x; 2422 }; 2423 2424 false: 2425 struct foo { 2426 int x; 2427 }; 2428 2429 * ``bool AfterUnion`` Wrap union definitions. 2430 2431 .. code-block:: c++ 2432 2433 true: 2434 union foo 2435 { 2436 int x; 2437 } 2438 2439 false: 2440 union foo { 2441 int x; 2442 } 2443 2444 * ``bool AfterExternBlock`` Wrap extern blocks. 2445 2446 .. code-block:: c++ 2447 2448 true: 2449 extern "C" 2450 { 2451 int foo(); 2452 } 2453 2454 false: 2455 extern "C" { 2456 int foo(); 2457 } 2458 2459 * ``bool BeforeCatch`` Wrap before ``catch``. 2460 2461 .. code-block:: c++ 2462 2463 true: 2464 try { 2465 foo(); 2466 } 2467 catch () { 2468 } 2469 2470 false: 2471 try { 2472 foo(); 2473 } catch () { 2474 } 2475 2476 * ``bool BeforeElse`` Wrap before ``else``. 2477 2478 .. code-block:: c++ 2479 2480 true: 2481 if (foo()) { 2482 } 2483 else { 2484 } 2485 2486 false: 2487 if (foo()) { 2488 } else { 2489 } 2490 2491 * ``bool BeforeLambdaBody`` Wrap lambda block. 2492 2493 .. code-block:: c++ 2494 2495 true: 2496 connect( 2497 []() 2498 { 2499 foo(); 2500 bar(); 2501 }); 2502 2503 false: 2504 connect([]() { 2505 foo(); 2506 bar(); 2507 }); 2508 2509 * ``bool BeforeWhile`` Wrap before ``while``. 2510 2511 .. code-block:: c++ 2512 2513 true: 2514 do { 2515 foo(); 2516 } 2517 while (1); 2518 2519 false: 2520 do { 2521 foo(); 2522 } while (1); 2523 2524 * ``bool IndentBraces`` Indent the wrapped braces themselves. 2525 2526 * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line. 2527 This option is used only if the opening brace of the function has 2528 already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is 2529 set, and the function could/should not be put on a single line (as per 2530 ``AllowShortFunctionsOnASingleLine`` and constructor formatting 2531 options). 2532 2533 .. code-block:: c++ 2534 2535 false: true: 2536 int f() vs. int f() 2537 {} { 2538 } 2539 2540 * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body 2541 can be put on a single line. This option is used only if the opening 2542 brace of the record has already been wrapped, i.e. the ``AfterClass`` 2543 (for classes) brace wrapping mode is set. 2544 2545 .. code-block:: c++ 2546 2547 false: true: 2548 class Foo vs. class Foo 2549 {} { 2550 } 2551 2552 * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line. 2553 This option is used only if the opening brace of the namespace has 2554 already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is 2555 set. 2556 2557 .. code-block:: c++ 2558 2559 false: true: 2560 namespace Foo vs. namespace Foo 2561 {} { 2562 } 2563 2564 2565.. _BracedInitializerIndentWidth: 2566 2567**BracedInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 17` :ref:`¶ <BracedInitializerIndentWidth>` 2568 The number of columns to use to indent the contents of braced init lists. 2569 If unset, ``ContinuationIndentWidth`` is used. 2570 2571 .. code-block:: c++ 2572 2573 AlignAfterOpenBracket: AlwaysBreak 2574 BracedInitializerIndentWidth: 2 2575 2576 void f() { 2577 SomeClass c{ 2578 "foo", 2579 "bar", 2580 "baz", 2581 }; 2582 auto s = SomeStruct{ 2583 .foo = "foo", 2584 .bar = "bar", 2585 .baz = "baz", 2586 }; 2587 SomeArrayT a[3] = { 2588 { 2589 foo, 2590 bar, 2591 }, 2592 { 2593 foo, 2594 bar, 2595 }, 2596 SomeArrayT{}, 2597 }; 2598 } 2599 2600.. _BreakAdjacentStringLiterals: 2601 2602**BreakAdjacentStringLiterals** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <BreakAdjacentStringLiterals>` 2603 Break between adjacent string literals. 2604 2605 .. code-block:: c++ 2606 2607 true: 2608 return "Code" 2609 "\0\52\26\55\55\0" 2610 "x013" 2611 "\02\xBA"; 2612 false: 2613 return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA"; 2614 2615.. _BreakAfterAttributes: 2616 2617**BreakAfterAttributes** (``AttributeBreakingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakAfterAttributes>` 2618 Break after a group of C++11 attributes before variable or function 2619 (including constructor/destructor) declaration/definition names or before 2620 control statements, i.e. ``if``, ``switch`` (including ``case`` and 2621 ``default`` labels), ``for``, and ``while`` statements. 2622 2623 Possible values: 2624 2625 * ``ABS_Always`` (in configuration: ``Always``) 2626 Always break after attributes. 2627 2628 .. code-block:: c++ 2629 2630 [[maybe_unused]] 2631 const int i; 2632 [[gnu::const]] [[maybe_unused]] 2633 int j; 2634 2635 [[nodiscard]] 2636 inline int f(); 2637 [[gnu::const]] [[nodiscard]] 2638 int g(); 2639 2640 [[likely]] 2641 if (a) 2642 f(); 2643 else 2644 g(); 2645 2646 switch (b) { 2647 [[unlikely]] 2648 case 1: 2649 ++b; 2650 break; 2651 [[likely]] 2652 default: 2653 return; 2654 } 2655 2656 * ``ABS_Leave`` (in configuration: ``Leave``) 2657 Leave the line breaking after attributes as is. 2658 2659 .. code-block:: c++ 2660 2661 [[maybe_unused]] const int i; 2662 [[gnu::const]] [[maybe_unused]] 2663 int j; 2664 2665 [[nodiscard]] inline int f(); 2666 [[gnu::const]] [[nodiscard]] 2667 int g(); 2668 2669 [[likely]] if (a) 2670 f(); 2671 else 2672 g(); 2673 2674 switch (b) { 2675 [[unlikely]] case 1: 2676 ++b; 2677 break; 2678 [[likely]] 2679 default: 2680 return; 2681 } 2682 2683 * ``ABS_Never`` (in configuration: ``Never``) 2684 Never break after attributes. 2685 2686 .. code-block:: c++ 2687 2688 [[maybe_unused]] const int i; 2689 [[gnu::const]] [[maybe_unused]] int j; 2690 2691 [[nodiscard]] inline int f(); 2692 [[gnu::const]] [[nodiscard]] int g(); 2693 2694 [[likely]] if (a) 2695 f(); 2696 else 2697 g(); 2698 2699 switch (b) { 2700 [[unlikely]] case 1: 2701 ++b; 2702 break; 2703 [[likely]] default: 2704 return; 2705 } 2706 2707 2708 2709.. _BreakAfterJavaFieldAnnotations: 2710 2711**BreakAfterJavaFieldAnnotations** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <BreakAfterJavaFieldAnnotations>` 2712 Break after each annotation on a field in Java files. 2713 2714 .. code-block:: java 2715 2716 true: false: 2717 @Partial vs. @Partial @Mock DataLoad loader; 2718 @Mock 2719 DataLoad loader; 2720 2721.. _BreakAfterReturnType: 2722 2723**BreakAfterReturnType** (``ReturnTypeBreakingStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakAfterReturnType>` 2724 The function declaration return type breaking style to use. 2725 2726 Possible values: 2727 2728 * ``RTBS_None`` (in configuration: ``None``) 2729 This is **deprecated**. See ``Automatic`` below. 2730 2731 * ``RTBS_Automatic`` (in configuration: ``Automatic``) 2732 Break after return type based on ``PenaltyReturnTypeOnItsOwnLine``. 2733 2734 .. code-block:: c++ 2735 2736 class A { 2737 int f() { return 0; }; 2738 }; 2739 int f(); 2740 int f() { return 1; } 2741 int 2742 LongName::AnotherLongName(); 2743 2744 * ``RTBS_ExceptShortType`` (in configuration: ``ExceptShortType``) 2745 Same as ``Automatic`` above, except that there is no break after short 2746 return types. 2747 2748 .. code-block:: c++ 2749 2750 class A { 2751 int f() { return 0; }; 2752 }; 2753 int f(); 2754 int f() { return 1; } 2755 int LongName:: 2756 AnotherLongName(); 2757 2758 * ``RTBS_All`` (in configuration: ``All``) 2759 Always break after the return type. 2760 2761 .. code-block:: c++ 2762 2763 class A { 2764 int 2765 f() { 2766 return 0; 2767 }; 2768 }; 2769 int 2770 f(); 2771 int 2772 f() { 2773 return 1; 2774 } 2775 int 2776 LongName::AnotherLongName(); 2777 2778 * ``RTBS_TopLevel`` (in configuration: ``TopLevel``) 2779 Always break after the return types of top-level functions. 2780 2781 .. code-block:: c++ 2782 2783 class A { 2784 int f() { return 0; }; 2785 }; 2786 int 2787 f(); 2788 int 2789 f() { 2790 return 1; 2791 } 2792 int 2793 LongName::AnotherLongName(); 2794 2795 * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``) 2796 Always break after the return type of function definitions. 2797 2798 .. code-block:: c++ 2799 2800 class A { 2801 int 2802 f() { 2803 return 0; 2804 }; 2805 }; 2806 int f(); 2807 int 2808 f() { 2809 return 1; 2810 } 2811 int 2812 LongName::AnotherLongName(); 2813 2814 * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``) 2815 Always break after the return type of top-level definitions. 2816 2817 .. code-block:: c++ 2818 2819 class A { 2820 int f() { return 0; }; 2821 }; 2822 int f(); 2823 int 2824 f() { 2825 return 1; 2826 } 2827 int 2828 LongName::AnotherLongName(); 2829 2830 2831 2832.. _BreakArrays: 2833 2834**BreakArrays** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <BreakArrays>` 2835 If ``true``, clang-format will always break after a Json array ``[`` 2836 otherwise it will scan until the closing ``]`` to determine if it should 2837 add newlines between elements (prettier compatible). 2838 2839 2840 .. note:: 2841 2842 This is currently only for formatting JSON. 2843 2844 .. code-block:: c++ 2845 2846 true: false: 2847 [ vs. [1, 2, 3, 4] 2848 1, 2849 2, 2850 3, 2851 4 2852 ] 2853 2854.. _BreakBeforeBinaryOperators: 2855 2856**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) :versionbadge:`clang-format 3.6` :ref:`¶ <BreakBeforeBinaryOperators>` 2857 The way to wrap binary operators. 2858 2859 Possible values: 2860 2861 * ``BOS_None`` (in configuration: ``None``) 2862 Break after operators. 2863 2864 .. code-block:: c++ 2865 2866 LooooooooooongType loooooooooooooooooooooongVariable = 2867 someLooooooooooooooooongFunction(); 2868 2869 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa + 2870 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa == 2871 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa && 2872 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > 2873 ccccccccccccccccccccccccccccccccccccccccc; 2874 2875 * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``) 2876 Break before operators that aren't assignments. 2877 2878 .. code-block:: c++ 2879 2880 LooooooooooongType loooooooooooooooooooooongVariable = 2881 someLooooooooooooooooongFunction(); 2882 2883 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2884 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2885 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2886 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2887 > ccccccccccccccccccccccccccccccccccccccccc; 2888 2889 * ``BOS_All`` (in configuration: ``All``) 2890 Break before operators. 2891 2892 .. code-block:: c++ 2893 2894 LooooooooooongType loooooooooooooooooooooongVariable 2895 = someLooooooooooooooooongFunction(); 2896 2897 bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2898 + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2899 == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2900 && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 2901 > ccccccccccccccccccccccccccccccccccccccccc; 2902 2903 2904 2905.. _BreakBeforeBraces: 2906 2907**BreakBeforeBraces** (``BraceBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeBraces>` 2908 The brace breaking style to use. 2909 2910 Possible values: 2911 2912 * ``BS_Attach`` (in configuration: ``Attach``) 2913 Always attach braces to surrounding context. 2914 2915 .. code-block:: c++ 2916 2917 namespace N { 2918 enum E { 2919 E1, 2920 E2, 2921 }; 2922 2923 class C { 2924 public: 2925 C(); 2926 }; 2927 2928 bool baz(int i) { 2929 try { 2930 do { 2931 switch (i) { 2932 case 1: { 2933 foobar(); 2934 break; 2935 } 2936 default: { 2937 break; 2938 } 2939 } 2940 } while (--i); 2941 return true; 2942 } catch (...) { 2943 handleError(); 2944 return false; 2945 } 2946 } 2947 2948 void foo(bool b) { 2949 if (b) { 2950 baz(2); 2951 } else { 2952 baz(5); 2953 } 2954 } 2955 2956 void bar() { foo(true); } 2957 } // namespace N 2958 2959 * ``BS_Linux`` (in configuration: ``Linux``) 2960 Like ``Attach``, but break before braces on function, namespace and 2961 class definitions. 2962 2963 .. code-block:: c++ 2964 2965 namespace N 2966 { 2967 enum E { 2968 E1, 2969 E2, 2970 }; 2971 2972 class C 2973 { 2974 public: 2975 C(); 2976 }; 2977 2978 bool baz(int i) 2979 { 2980 try { 2981 do { 2982 switch (i) { 2983 case 1: { 2984 foobar(); 2985 break; 2986 } 2987 default: { 2988 break; 2989 } 2990 } 2991 } while (--i); 2992 return true; 2993 } catch (...) { 2994 handleError(); 2995 return false; 2996 } 2997 } 2998 2999 void foo(bool b) 3000 { 3001 if (b) { 3002 baz(2); 3003 } else { 3004 baz(5); 3005 } 3006 } 3007 3008 void bar() { foo(true); } 3009 } // namespace N 3010 3011 * ``BS_Mozilla`` (in configuration: ``Mozilla``) 3012 Like ``Attach``, but break before braces on enum, function, and record 3013 definitions. 3014 3015 .. code-block:: c++ 3016 3017 namespace N { 3018 enum E 3019 { 3020 E1, 3021 E2, 3022 }; 3023 3024 class C 3025 { 3026 public: 3027 C(); 3028 }; 3029 3030 bool baz(int i) 3031 { 3032 try { 3033 do { 3034 switch (i) { 3035 case 1: { 3036 foobar(); 3037 break; 3038 } 3039 default: { 3040 break; 3041 } 3042 } 3043 } while (--i); 3044 return true; 3045 } catch (...) { 3046 handleError(); 3047 return false; 3048 } 3049 } 3050 3051 void foo(bool b) 3052 { 3053 if (b) { 3054 baz(2); 3055 } else { 3056 baz(5); 3057 } 3058 } 3059 3060 void bar() { foo(true); } 3061 } // namespace N 3062 3063 * ``BS_Stroustrup`` (in configuration: ``Stroustrup``) 3064 Like ``Attach``, but break before function definitions, ``catch``, and 3065 ``else``. 3066 3067 .. code-block:: c++ 3068 3069 namespace N { 3070 enum E { 3071 E1, 3072 E2, 3073 }; 3074 3075 class C { 3076 public: 3077 C(); 3078 }; 3079 3080 bool baz(int i) 3081 { 3082 try { 3083 do { 3084 switch (i) { 3085 case 1: { 3086 foobar(); 3087 break; 3088 } 3089 default: { 3090 break; 3091 } 3092 } 3093 } while (--i); 3094 return true; 3095 } 3096 catch (...) { 3097 handleError(); 3098 return false; 3099 } 3100 } 3101 3102 void foo(bool b) 3103 { 3104 if (b) { 3105 baz(2); 3106 } 3107 else { 3108 baz(5); 3109 } 3110 } 3111 3112 void bar() { foo(true); } 3113 } // namespace N 3114 3115 * ``BS_Allman`` (in configuration: ``Allman``) 3116 Always break before braces. 3117 3118 .. code-block:: c++ 3119 3120 namespace N 3121 { 3122 enum E 3123 { 3124 E1, 3125 E2, 3126 }; 3127 3128 class C 3129 { 3130 public: 3131 C(); 3132 }; 3133 3134 bool baz(int i) 3135 { 3136 try 3137 { 3138 do 3139 { 3140 switch (i) 3141 { 3142 case 1: 3143 { 3144 foobar(); 3145 break; 3146 } 3147 default: 3148 { 3149 break; 3150 } 3151 } 3152 } while (--i); 3153 return true; 3154 } 3155 catch (...) 3156 { 3157 handleError(); 3158 return false; 3159 } 3160 } 3161 3162 void foo(bool b) 3163 { 3164 if (b) 3165 { 3166 baz(2); 3167 } 3168 else 3169 { 3170 baz(5); 3171 } 3172 } 3173 3174 void bar() { foo(true); } 3175 } // namespace N 3176 3177 * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``) 3178 Like ``Allman`` but always indent braces and line up code with braces. 3179 3180 .. code-block:: c++ 3181 3182 namespace N 3183 { 3184 enum E 3185 { 3186 E1, 3187 E2, 3188 }; 3189 3190 class C 3191 { 3192 public: 3193 C(); 3194 }; 3195 3196 bool baz(int i) 3197 { 3198 try 3199 { 3200 do 3201 { 3202 switch (i) 3203 { 3204 case 1: 3205 { 3206 foobar(); 3207 break; 3208 } 3209 default: 3210 { 3211 break; 3212 } 3213 } 3214 } while (--i); 3215 return true; 3216 } 3217 catch (...) 3218 { 3219 handleError(); 3220 return false; 3221 } 3222 } 3223 3224 void foo(bool b) 3225 { 3226 if (b) 3227 { 3228 baz(2); 3229 } 3230 else 3231 { 3232 baz(5); 3233 } 3234 } 3235 3236 void bar() { foo(true); } 3237 } // namespace N 3238 3239 * ``BS_GNU`` (in configuration: ``GNU``) 3240 Always break before braces and add an extra level of indentation to 3241 braces of control statements, not to those of class, function 3242 or other definitions. 3243 3244 .. code-block:: c++ 3245 3246 namespace N 3247 { 3248 enum E 3249 { 3250 E1, 3251 E2, 3252 }; 3253 3254 class C 3255 { 3256 public: 3257 C(); 3258 }; 3259 3260 bool baz(int i) 3261 { 3262 try 3263 { 3264 do 3265 { 3266 switch (i) 3267 { 3268 case 1: 3269 { 3270 foobar(); 3271 break; 3272 } 3273 default: 3274 { 3275 break; 3276 } 3277 } 3278 } 3279 while (--i); 3280 return true; 3281 } 3282 catch (...) 3283 { 3284 handleError(); 3285 return false; 3286 } 3287 } 3288 3289 void foo(bool b) 3290 { 3291 if (b) 3292 { 3293 baz(2); 3294 } 3295 else 3296 { 3297 baz(5); 3298 } 3299 } 3300 3301 void bar() { foo(true); } 3302 } // namespace N 3303 3304 * ``BS_WebKit`` (in configuration: ``WebKit``) 3305 Like ``Attach``, but break before functions. 3306 3307 .. code-block:: c++ 3308 3309 namespace N { 3310 enum E { 3311 E1, 3312 E2, 3313 }; 3314 3315 class C { 3316 public: 3317 C(); 3318 }; 3319 3320 bool baz(int i) 3321 { 3322 try { 3323 do { 3324 switch (i) { 3325 case 1: { 3326 foobar(); 3327 break; 3328 } 3329 default: { 3330 break; 3331 } 3332 } 3333 } while (--i); 3334 return true; 3335 } catch (...) { 3336 handleError(); 3337 return false; 3338 } 3339 } 3340 3341 void foo(bool b) 3342 { 3343 if (b) { 3344 baz(2); 3345 } else { 3346 baz(5); 3347 } 3348 } 3349 3350 void bar() { foo(true); } 3351 } // namespace N 3352 3353 * ``BS_Custom`` (in configuration: ``Custom``) 3354 Configure each individual brace in ``BraceWrapping``. 3355 3356 3357 3358.. _BreakBeforeConceptDeclarations: 3359 3360**BreakBeforeConceptDeclarations** (``BreakBeforeConceptDeclarationsStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BreakBeforeConceptDeclarations>` 3361 The concept declaration style to use. 3362 3363 Possible values: 3364 3365 * ``BBCDS_Never`` (in configuration: ``Never``) 3366 Keep the template declaration line together with ``concept``. 3367 3368 .. code-block:: c++ 3369 3370 template <typename T> concept C = ...; 3371 3372 * ``BBCDS_Allowed`` (in configuration: ``Allowed``) 3373 Breaking between template declaration and ``concept`` is allowed. The 3374 actual behavior depends on the content and line breaking rules and 3375 penalties. 3376 3377 * ``BBCDS_Always`` (in configuration: ``Always``) 3378 Always break before ``concept``, putting it in the line after the 3379 template declaration. 3380 3381 .. code-block:: c++ 3382 3383 template <typename T> 3384 concept C = ...; 3385 3386 3387 3388.. _BreakBeforeInlineASMColon: 3389 3390**BreakBeforeInlineASMColon** (``BreakBeforeInlineASMColonStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakBeforeInlineASMColon>` 3391 The inline ASM colon style to use. 3392 3393 Possible values: 3394 3395 * ``BBIAS_Never`` (in configuration: ``Never``) 3396 No break before inline ASM colon. 3397 3398 .. code-block:: c++ 3399 3400 asm volatile("string", : : val); 3401 3402 * ``BBIAS_OnlyMultiline`` (in configuration: ``OnlyMultiline``) 3403 Break before inline ASM colon if the line length is longer than column 3404 limit. 3405 3406 .. code-block:: c++ 3407 3408 asm volatile("string", : : val); 3409 asm("cmoveq %1, %2, %[result]" 3410 : [result] "=r"(result) 3411 : "r"(test), "r"(new), "[result]"(old)); 3412 3413 * ``BBIAS_Always`` (in configuration: ``Always``) 3414 Always break before inline ASM colon. 3415 3416 .. code-block:: c++ 3417 3418 asm volatile("string", 3419 : 3420 : val); 3421 3422 3423 3424.. _BreakBeforeTernaryOperators: 3425 3426**BreakBeforeTernaryOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeTernaryOperators>` 3427 If ``true``, ternary operators will be placed after line breaks. 3428 3429 .. code-block:: c++ 3430 3431 true: 3432 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription 3433 ? firstValue 3434 : SecondValueVeryVeryVeryVeryLong; 3435 3436 false: 3437 veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? 3438 firstValue : 3439 SecondValueVeryVeryVeryVeryLong; 3440 3441.. _BreakBinaryOperations: 3442 3443**BreakBinaryOperations** (``BreakBinaryOperationsStyle``) :versionbadge:`clang-format 20` :ref:`¶ <BreakBinaryOperations>` 3444 The break binary operations style to use. 3445 3446 Possible values: 3447 3448 * ``BBO_Never`` (in configuration: ``Never``) 3449 Don't break binary operations 3450 3451 .. code-block:: c++ 3452 3453 aaa + bbbb * ccccc - ddddd + 3454 eeeeeeeeeeeeeeee; 3455 3456 * ``BBO_OnePerLine`` (in configuration: ``OnePerLine``) 3457 Binary operations will either be all on the same line, or each operation 3458 will have one line each. 3459 3460 .. code-block:: c++ 3461 3462 aaa + 3463 bbbb * 3464 ccccc - 3465 ddddd + 3466 eeeeeeeeeeeeeeee; 3467 3468 * ``BBO_RespectPrecedence`` (in configuration: ``RespectPrecedence``) 3469 Binary operations of a particular precedence that exceed the column 3470 limit will have one line each. 3471 3472 .. code-block:: c++ 3473 3474 aaa + 3475 bbbb * ccccc - 3476 ddddd + 3477 eeeeeeeeeeeeeeee; 3478 3479 3480 3481.. _BreakConstructorInitializers: 3482 3483**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) :versionbadge:`clang-format 5` :ref:`¶ <BreakConstructorInitializers>` 3484 The break constructor initializers style to use. 3485 3486 Possible values: 3487 3488 * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) 3489 Break constructor initializers before the colon and after the commas. 3490 3491 .. code-block:: c++ 3492 3493 Constructor() 3494 : initializer1(), 3495 initializer2() 3496 3497 * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) 3498 Break constructor initializers before the colon and commas, and align 3499 the commas with the colon. 3500 3501 .. code-block:: c++ 3502 3503 Constructor() 3504 : initializer1() 3505 , initializer2() 3506 3507 * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) 3508 Break constructor initializers after the colon and commas. 3509 3510 .. code-block:: c++ 3511 3512 Constructor() : 3513 initializer1(), 3514 initializer2() 3515 3516 3517 3518.. _BreakFunctionDefinitionParameters: 3519 3520**BreakFunctionDefinitionParameters** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <BreakFunctionDefinitionParameters>` 3521 If ``true``, clang-format will always break before function definition 3522 parameters. 3523 3524 .. code-block:: c++ 3525 3526 true: 3527 void functionDefinition( 3528 int A, int B) {} 3529 3530 false: 3531 void functionDefinition(int A, int B) {} 3532 3533.. _BreakInheritanceList: 3534 3535**BreakInheritanceList** (``BreakInheritanceListStyle``) :versionbadge:`clang-format 7` :ref:`¶ <BreakInheritanceList>` 3536 The inheritance list style to use. 3537 3538 Possible values: 3539 3540 * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``) 3541 Break inheritance list before the colon and after the commas. 3542 3543 .. code-block:: c++ 3544 3545 class Foo 3546 : Base1, 3547 Base2 3548 {}; 3549 3550 * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``) 3551 Break inheritance list before the colon and commas, and align 3552 the commas with the colon. 3553 3554 .. code-block:: c++ 3555 3556 class Foo 3557 : Base1 3558 , Base2 3559 {}; 3560 3561 * ``BILS_AfterColon`` (in configuration: ``AfterColon``) 3562 Break inheritance list after the colon and commas. 3563 3564 .. code-block:: c++ 3565 3566 class Foo : 3567 Base1, 3568 Base2 3569 {}; 3570 3571 * ``BILS_AfterComma`` (in configuration: ``AfterComma``) 3572 Break inheritance list only after the commas. 3573 3574 .. code-block:: c++ 3575 3576 class Foo : Base1, 3577 Base2 3578 {}; 3579 3580 3581 3582.. _BreakStringLiterals: 3583 3584**BreakStringLiterals** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <BreakStringLiterals>` 3585 Allow breaking string literals when formatting. 3586 3587 In C, C++, and Objective-C: 3588 3589 .. code-block:: c++ 3590 3591 true: 3592 const char* x = "veryVeryVeryVeryVeryVe" 3593 "ryVeryVeryVeryVeryVery" 3594 "VeryLongString"; 3595 3596 false: 3597 const char* x = 3598 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; 3599 3600 In C# and Java: 3601 3602 .. code-block:: c++ 3603 3604 true: 3605 string x = "veryVeryVeryVeryVeryVe" + 3606 "ryVeryVeryVeryVeryVery" + 3607 "VeryLongString"; 3608 3609 false: 3610 string x = 3611 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; 3612 3613 C# interpolated strings are not broken. 3614 3615 In Verilog: 3616 3617 .. code-block:: c++ 3618 3619 true: 3620 string x = {"veryVeryVeryVeryVeryVe", 3621 "ryVeryVeryVeryVeryVery", 3622 "VeryLongString"}; 3623 3624 false: 3625 string x = 3626 "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; 3627 3628.. _BreakTemplateDeclarations: 3629 3630**BreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakTemplateDeclarations>` 3631 The template declaration breaking style to use. 3632 3633 Possible values: 3634 3635 * ``BTDS_Leave`` (in configuration: ``Leave``) 3636 Do not change the line breaking before the declaration. 3637 3638 .. code-block:: c++ 3639 3640 template <typename T> 3641 T foo() { 3642 } 3643 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, 3644 int bbbbbbbbbbbbbbbbbbbbb) { 3645 } 3646 3647 * ``BTDS_No`` (in configuration: ``No``) 3648 Do not force break before declaration. 3649 ``PenaltyBreakTemplateDeclaration`` is taken into account. 3650 3651 .. code-block:: c++ 3652 3653 template <typename T> T foo() { 3654 } 3655 template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa, 3656 int bbbbbbbbbbbbbbbbbbbbb) { 3657 } 3658 3659 * ``BTDS_MultiLine`` (in configuration: ``MultiLine``) 3660 Force break after template declaration only when the following 3661 declaration spans multiple lines. 3662 3663 .. code-block:: c++ 3664 3665 template <typename T> T foo() { 3666 } 3667 template <typename T> 3668 T foo(int aaaaaaaaaaaaaaaaaaaaa, 3669 int bbbbbbbbbbbbbbbbbbbbb) { 3670 } 3671 3672 * ``BTDS_Yes`` (in configuration: ``Yes``) 3673 Always break after template declaration. 3674 3675 .. code-block:: c++ 3676 3677 template <typename T> 3678 T foo() { 3679 } 3680 template <typename T> 3681 T foo(int aaaaaaaaaaaaaaaaaaaaa, 3682 int bbbbbbbbbbbbbbbbbbbbb) { 3683 } 3684 3685 3686 3687.. _ColumnLimit: 3688 3689**ColumnLimit** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ColumnLimit>` 3690 The column limit. 3691 3692 A column limit of ``0`` means that there is no column limit. In this case, 3693 clang-format will respect the input's line breaking decisions within 3694 statements unless they contradict other rules. 3695 3696.. _CommentPragmas: 3697 3698**CommentPragmas** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <CommentPragmas>` 3699 A regular expression that describes comments with special meaning, 3700 which should not be split into lines or otherwise changed. 3701 3702 .. code-block:: c++ 3703 3704 // CommentPragmas: '^ FOOBAR pragma:' 3705 // Will leave the following line unaffected 3706 #include <vector> // FOOBAR pragma: keep 3707 3708.. _CompactNamespaces: 3709 3710**CompactNamespaces** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <CompactNamespaces>` 3711 If ``true``, consecutive namespace declarations will be on the same 3712 line. If ``false``, each namespace is declared on a new line. 3713 3714 .. code-block:: c++ 3715 3716 true: 3717 namespace Foo { namespace Bar { 3718 }} 3719 3720 false: 3721 namespace Foo { 3722 namespace Bar { 3723 } 3724 } 3725 3726 If it does not fit on a single line, the overflowing namespaces get 3727 wrapped: 3728 3729 .. code-block:: c++ 3730 3731 namespace Foo { namespace Bar { 3732 namespace Extra { 3733 }}} 3734 3735.. _ConstructorInitializerAllOnOneLineOrOnePerLine: 3736 3737**ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerAllOnOneLineOrOnePerLine>` 3738 This option is **deprecated**. See ``CurrentLine`` of 3739 ``PackConstructorInitializers``. 3740 3741.. _ConstructorInitializerIndentWidth: 3742 3743**ConstructorInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerIndentWidth>` 3744 The number of characters to use for indentation of constructor 3745 initializer lists as well as inheritance lists. 3746 3747.. _ContinuationIndentWidth: 3748 3749**ContinuationIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ContinuationIndentWidth>` 3750 Indent width for line continuations. 3751 3752 .. code-block:: c++ 3753 3754 ContinuationIndentWidth: 2 3755 3756 int i = // VeryVeryVeryVeryVeryLongComment 3757 longFunction( // Again a long comment 3758 arg); 3759 3760.. _Cpp11BracedListStyle: 3761 3762**Cpp11BracedListStyle** (``Boolean``) :versionbadge:`clang-format 3.4` :ref:`¶ <Cpp11BracedListStyle>` 3763 If ``true``, format braced lists as best suited for C++11 braced 3764 lists. 3765 3766 Important differences: 3767 3768 * No spaces inside the braced list. 3769 * No line break before the closing brace. 3770 * Indentation with the continuation indent, not with the block indent. 3771 3772 Fundamentally, C++11 braced lists are formatted exactly like function 3773 calls would be formatted in their place. If the braced list follows a name 3774 (e.g. a type or variable name), clang-format formats as if the ``{}`` were 3775 the parentheses of a function call with that name. If there is no name, 3776 a zero-length name is assumed. 3777 3778 .. code-block:: c++ 3779 3780 true: false: 3781 vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 }; 3782 vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} }; 3783 f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); 3784 new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; 3785 3786.. _DeriveLineEnding: 3787 3788**DeriveLineEnding** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <DeriveLineEnding>` 3789 This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of 3790 ``LineEnding``. 3791 3792.. _DerivePointerAlignment: 3793 3794**DerivePointerAlignment** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DerivePointerAlignment>` 3795 If ``true``, analyze the formatted file for the most common 3796 alignment of ``&`` and ``*``. 3797 Pointer and reference alignment styles are going to be updated according 3798 to the preferences found in the file. 3799 ``PointerAlignment`` is then used only as fallback. 3800 3801.. _DisableFormat: 3802 3803**DisableFormat** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DisableFormat>` 3804 Disables formatting completely. 3805 3806.. _EmptyLineAfterAccessModifier: 3807 3808**EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) :versionbadge:`clang-format 13` :ref:`¶ <EmptyLineAfterAccessModifier>` 3809 Defines when to put an empty line after access modifiers. 3810 ``EmptyLineBeforeAccessModifier`` configuration handles the number of 3811 empty lines between two access modifiers. 3812 3813 Possible values: 3814 3815 * ``ELAAMS_Never`` (in configuration: ``Never``) 3816 Remove all empty lines after access modifiers. 3817 3818 .. code-block:: c++ 3819 3820 struct foo { 3821 private: 3822 int i; 3823 protected: 3824 int j; 3825 /* comment */ 3826 public: 3827 foo() {} 3828 private: 3829 protected: 3830 }; 3831 3832 * ``ELAAMS_Leave`` (in configuration: ``Leave``) 3833 Keep existing empty lines after access modifiers. 3834 MaxEmptyLinesToKeep is applied instead. 3835 3836 * ``ELAAMS_Always`` (in configuration: ``Always``) 3837 Always add empty line after access modifiers if there are none. 3838 MaxEmptyLinesToKeep is applied also. 3839 3840 .. code-block:: c++ 3841 3842 struct foo { 3843 private: 3844 3845 int i; 3846 protected: 3847 3848 int j; 3849 /* comment */ 3850 public: 3851 3852 foo() {} 3853 private: 3854 3855 protected: 3856 3857 }; 3858 3859 3860 3861.. _EmptyLineBeforeAccessModifier: 3862 3863**EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) :versionbadge:`clang-format 12` :ref:`¶ <EmptyLineBeforeAccessModifier>` 3864 Defines in which cases to put empty line before access modifiers. 3865 3866 Possible values: 3867 3868 * ``ELBAMS_Never`` (in configuration: ``Never``) 3869 Remove all empty lines before access modifiers. 3870 3871 .. code-block:: c++ 3872 3873 struct foo { 3874 private: 3875 int i; 3876 protected: 3877 int j; 3878 /* comment */ 3879 public: 3880 foo() {} 3881 private: 3882 protected: 3883 }; 3884 3885 * ``ELBAMS_Leave`` (in configuration: ``Leave``) 3886 Keep existing empty lines before access modifiers. 3887 3888 * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``) 3889 Add empty line only when access modifier starts a new logical block. 3890 Logical block is a group of one or more member fields or functions. 3891 3892 .. code-block:: c++ 3893 3894 struct foo { 3895 private: 3896 int i; 3897 3898 protected: 3899 int j; 3900 /* comment */ 3901 public: 3902 foo() {} 3903 3904 private: 3905 protected: 3906 }; 3907 3908 * ``ELBAMS_Always`` (in configuration: ``Always``) 3909 Always add empty line before access modifiers unless access modifier 3910 is at the start of struct or class definition. 3911 3912 .. code-block:: c++ 3913 3914 struct foo { 3915 private: 3916 int i; 3917 3918 protected: 3919 int j; 3920 /* comment */ 3921 3922 public: 3923 foo() {} 3924 3925 private: 3926 3927 protected: 3928 }; 3929 3930 3931 3932.. _ExperimentalAutoDetectBinPacking: 3933 3934**ExperimentalAutoDetectBinPacking** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ExperimentalAutoDetectBinPacking>` 3935 If ``true``, clang-format detects whether function calls and 3936 definitions are formatted with one parameter per line. 3937 3938 Each call can be bin-packed, one-per-line or inconclusive. If it is 3939 inconclusive, e.g. completely on one line, but a decision needs to be 3940 made, clang-format analyzes whether there are other bin-packed cases in 3941 the input file and act accordingly. 3942 3943 3944 .. note:: 3945 3946 This is an experimental flag, that might go away or be renamed. Do 3947 not use this in config files, etc. Use at your own risk. 3948 3949.. _FixNamespaceComments: 3950 3951**FixNamespaceComments** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <FixNamespaceComments>` 3952 If ``true``, clang-format adds missing namespace end comments for 3953 namespaces and fixes invalid existing ones. This doesn't affect short 3954 namespaces, which are controlled by ``ShortNamespaceLines``. 3955 3956 .. code-block:: c++ 3957 3958 true: false: 3959 namespace longNamespace { vs. namespace longNamespace { 3960 void foo(); void foo(); 3961 void bar(); void bar(); 3962 } // namespace a } 3963 namespace shortNamespace { namespace shortNamespace { 3964 void baz(); void baz(); 3965 } } 3966 3967.. _ForEachMacros: 3968 3969**ForEachMacros** (``List of Strings``) :versionbadge:`clang-format 3.7` :ref:`¶ <ForEachMacros>` 3970 A vector of macros that should be interpreted as foreach loops 3971 instead of as function calls. 3972 3973 These are expected to be macros of the form: 3974 3975 .. code-block:: c++ 3976 3977 FOREACH(<variable-declaration>, ...) 3978 <loop-body> 3979 3980 In the .clang-format configuration file, this can be configured like: 3981 3982 .. code-block:: yaml 3983 3984 ForEachMacros: [RANGES_FOR, FOREACH] 3985 3986 For example: BOOST_FOREACH. 3987 3988.. _IfMacros: 3989 3990**IfMacros** (``List of Strings``) :versionbadge:`clang-format 13` :ref:`¶ <IfMacros>` 3991 A vector of macros that should be interpreted as conditionals 3992 instead of as function calls. 3993 3994 These are expected to be macros of the form: 3995 3996 .. code-block:: c++ 3997 3998 IF(...) 3999 <conditional-body> 4000 else IF(...) 4001 <conditional-body> 4002 4003 In the .clang-format configuration file, this can be configured like: 4004 4005 .. code-block:: yaml 4006 4007 IfMacros: [IF] 4008 4009 For example: `KJ_IF_MAYBE 4010 <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_ 4011 4012.. _IncludeBlocks: 4013 4014**IncludeBlocks** (``IncludeBlocksStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IncludeBlocks>` 4015 Dependent on the value, multiple ``#include`` blocks can be sorted 4016 as one and divided based on category. 4017 4018 Possible values: 4019 4020 * ``IBS_Preserve`` (in configuration: ``Preserve``) 4021 Sort each ``#include`` block separately. 4022 4023 .. code-block:: c++ 4024 4025 #include "b.h" into #include "b.h" 4026 4027 #include <lib/main.h> #include "a.h" 4028 #include "a.h" #include <lib/main.h> 4029 4030 * ``IBS_Merge`` (in configuration: ``Merge``) 4031 Merge multiple ``#include`` blocks together and sort as one. 4032 4033 .. code-block:: c++ 4034 4035 #include "b.h" into #include "a.h" 4036 #include "b.h" 4037 #include <lib/main.h> #include <lib/main.h> 4038 #include "a.h" 4039 4040 * ``IBS_Regroup`` (in configuration: ``Regroup``) 4041 Merge multiple ``#include`` blocks together and sort as one. 4042 Then split into groups based on category priority. See 4043 ``IncludeCategories``. 4044 4045 .. code-block:: c++ 4046 4047 #include "b.h" into #include "a.h" 4048 #include "b.h" 4049 #include <lib/main.h> 4050 #include "a.h" #include <lib/main.h> 4051 4052 4053 4054.. _IncludeCategories: 4055 4056**IncludeCategories** (``List of IncludeCategories``) :versionbadge:`clang-format 3.8` :ref:`¶ <IncludeCategories>` 4057 Regular expressions denoting the different ``#include`` categories 4058 used for ordering ``#includes``. 4059 4060 `POSIX extended 4061 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_ 4062 regular expressions are supported. 4063 4064 These regular expressions are matched against the filename of an include 4065 (including the <> or "") in order. The value belonging to the first 4066 matching regular expression is assigned and ``#includes`` are sorted first 4067 according to increasing category number and then alphabetically within 4068 each category. 4069 4070 If none of the regular expressions match, INT_MAX is assigned as 4071 category. The main header for a source file automatically gets category 0. 4072 so that it is generally kept at the beginning of the ``#includes`` 4073 (https://llvm.org/docs/CodingStandards.html#include-style). However, you 4074 can also assign negative priorities if you have certain headers that 4075 always need to be first. 4076 4077 There is a third and optional field ``SortPriority`` which can used while 4078 ``IncludeBlocks = IBS_Regroup`` to define the priority in which 4079 ``#includes`` should be ordered. The value of ``Priority`` defines the 4080 order of ``#include blocks`` and also allows the grouping of ``#includes`` 4081 of different priority. ``SortPriority`` is set to the value of 4082 ``Priority`` as default if it is not assigned. 4083 4084 Each regular expression can be marked as case sensitive with the field 4085 ``CaseSensitive``, per default it is not. 4086 4087 To configure this in the .clang-format file, use: 4088 4089 .. code-block:: yaml 4090 4091 IncludeCategories: 4092 - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 4093 Priority: 2 4094 SortPriority: 2 4095 CaseSensitive: true 4096 - Regex: '^((<|")(gtest|gmock|isl|json)/)' 4097 Priority: 3 4098 - Regex: '<[[:alnum:].]+>' 4099 Priority: 4 4100 - Regex: '.*' 4101 Priority: 1 4102 SortPriority: 0 4103 4104.. _IncludeIsMainRegex: 4105 4106**IncludeIsMainRegex** (``String``) :versionbadge:`clang-format 3.9` :ref:`¶ <IncludeIsMainRegex>` 4107 Specify a regular expression of suffixes that are allowed in the 4108 file-to-main-include mapping. 4109 4110 When guessing whether a #include is the "main" include (to assign 4111 category 0, see above), use this regex of allowed suffixes to the header 4112 stem. A partial match is done, so that: 4113 * ``""`` means "arbitrary suffix" 4114 * ``"$"`` means "no suffix" 4115 4116 For example, if configured to ``"(_test)?$"``, then a header a.h would be seen 4117 as the "main" include in both a.cc and a_test.cc. 4118 4119.. _IncludeIsMainSourceRegex: 4120 4121**IncludeIsMainSourceRegex** (``String``) :versionbadge:`clang-format 10` :ref:`¶ <IncludeIsMainSourceRegex>` 4122 Specify a regular expression for files being formatted 4123 that are allowed to be considered "main" in the 4124 file-to-main-include mapping. 4125 4126 By default, clang-format considers files as "main" only when they end 4127 with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm`` 4128 extensions. 4129 For these files a guessing of "main" include takes place 4130 (to assign category 0, see above). This config option allows for 4131 additional suffixes and extensions for files to be considered as "main". 4132 4133 For example, if this option is configured to ``(Impl\.hpp)$``, 4134 then a file ``ClassImpl.hpp`` is considered "main" (in addition to 4135 ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main 4136 include file" logic will be executed (with *IncludeIsMainRegex* setting 4137 also being respected in later phase). Without this option set, 4138 ``ClassImpl.hpp`` would not have the main include file put on top 4139 before any other include. 4140 4141.. _IndentAccessModifiers: 4142 4143**IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13` :ref:`¶ <IndentAccessModifiers>` 4144 Specify whether access modifiers should have their own indentation level. 4145 4146 When ``false``, access modifiers are indented (or outdented) relative to 4147 the record members, respecting the ``AccessModifierOffset``. Record 4148 members are indented one level below the record. 4149 When ``true``, access modifiers get their own indentation level. As a 4150 consequence, record members are always indented 2 levels below the record, 4151 regardless of the access modifier presence. Value of the 4152 ``AccessModifierOffset`` is ignored. 4153 4154 .. code-block:: c++ 4155 4156 false: true: 4157 class C { vs. class C { 4158 class D { class D { 4159 void bar(); void bar(); 4160 protected: protected: 4161 D(); D(); 4162 }; }; 4163 public: public: 4164 C(); C(); 4165 }; }; 4166 void foo() { void foo() { 4167 return 1; return 1; 4168 } } 4169 4170.. _IndentCaseBlocks: 4171 4172**IndentCaseBlocks** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <IndentCaseBlocks>` 4173 Indent case label blocks one level from the case label. 4174 4175 When ``false``, the block following the case label uses the same 4176 indentation level as for the case label, treating the case label the same 4177 as an if-statement. 4178 When ``true``, the block gets indented as a scope block. 4179 4180 .. code-block:: c++ 4181 4182 false: true: 4183 switch (fool) { vs. switch (fool) { 4184 case 1: { case 1: 4185 bar(); { 4186 } break; bar(); 4187 default: { } 4188 plop(); break; 4189 } default: 4190 } { 4191 plop(); 4192 } 4193 } 4194 4195.. _IndentCaseLabels: 4196 4197**IndentCaseLabels** (``Boolean``) :versionbadge:`clang-format 3.3` :ref:`¶ <IndentCaseLabels>` 4198 Indent case labels one level from the switch statement. 4199 4200 When ``false``, use the same indentation level as for the switch 4201 statement. Switch statement body is always indented one level more than 4202 case labels (except the first block following the case label, which 4203 itself indents the code - unless IndentCaseBlocks is enabled). 4204 4205 .. code-block:: c++ 4206 4207 false: true: 4208 switch (fool) { vs. switch (fool) { 4209 case 1: case 1: 4210 bar(); bar(); 4211 break; break; 4212 default: default: 4213 plop(); plop(); 4214 } } 4215 4216.. _IndentExportBlock: 4217 4218**IndentExportBlock** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <IndentExportBlock>` 4219 If ``true``, clang-format will indent the body of an ``export { ... }`` 4220 block. This doesn't affect the formatting of anything else related to 4221 exported declarations. 4222 4223 .. code-block:: c++ 4224 4225 true: false: 4226 export { vs. export { 4227 void foo(); void foo(); 4228 void bar(); void bar(); 4229 } } 4230 4231.. _IndentExternBlock: 4232 4233**IndentExternBlock** (``IndentExternBlockStyle``) :versionbadge:`clang-format 11` :ref:`¶ <IndentExternBlock>` 4234 IndentExternBlockStyle is the type of indenting of extern blocks. 4235 4236 Possible values: 4237 4238 * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``) 4239 Backwards compatible with AfterExternBlock's indenting. 4240 4241 .. code-block:: c++ 4242 4243 IndentExternBlock: AfterExternBlock 4244 BraceWrapping.AfterExternBlock: true 4245 extern "C" 4246 { 4247 void foo(); 4248 } 4249 4250 4251 .. code-block:: c++ 4252 4253 IndentExternBlock: AfterExternBlock 4254 BraceWrapping.AfterExternBlock: false 4255 extern "C" { 4256 void foo(); 4257 } 4258 4259 * ``IEBS_NoIndent`` (in configuration: ``NoIndent``) 4260 Does not indent extern blocks. 4261 4262 .. code-block:: c++ 4263 4264 extern "C" { 4265 void foo(); 4266 } 4267 4268 * ``IEBS_Indent`` (in configuration: ``Indent``) 4269 Indents extern blocks. 4270 4271 .. code-block:: c++ 4272 4273 extern "C" { 4274 void foo(); 4275 } 4276 4277 4278 4279.. _IndentGotoLabels: 4280 4281**IndentGotoLabels** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <IndentGotoLabels>` 4282 Indent goto labels. 4283 4284 When ``false``, goto labels are flushed left. 4285 4286 .. code-block:: c++ 4287 4288 true: false: 4289 int f() { vs. int f() { 4290 if (foo()) { if (foo()) { 4291 label1: label1: 4292 bar(); bar(); 4293 } } 4294 label2: label2: 4295 return 1; return 1; 4296 } } 4297 4298.. _IndentPPDirectives: 4299 4300**IndentPPDirectives** (``PPDirectiveIndentStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IndentPPDirectives>` 4301 The preprocessor directive indenting style to use. 4302 4303 Possible values: 4304 4305 * ``PPDIS_None`` (in configuration: ``None``) 4306 Does not indent any directives. 4307 4308 .. code-block:: c++ 4309 4310 #if FOO 4311 #if BAR 4312 #include <foo> 4313 #endif 4314 #endif 4315 4316 * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``) 4317 Indents directives after the hash. 4318 4319 .. code-block:: c++ 4320 4321 #if FOO 4322 # if BAR 4323 # include <foo> 4324 # endif 4325 #endif 4326 4327 * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``) 4328 Indents directives before the hash. 4329 4330 .. code-block:: c++ 4331 4332 #if FOO 4333 #if BAR 4334 #include <foo> 4335 #endif 4336 #endif 4337 4338 4339 4340.. _IndentRequiresClause: 4341 4342**IndentRequiresClause** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <IndentRequiresClause>` 4343 Indent the requires clause in a template. This only applies when 4344 ``RequiresClausePosition`` is ``OwnLine``, ``OwnLineWithBrace``, 4345 or ``WithFollowing``. 4346 4347 In clang-format 12, 13 and 14 it was named ``IndentRequires``. 4348 4349 .. code-block:: c++ 4350 4351 true: 4352 template <typename It> 4353 requires Iterator<It> 4354 void sort(It begin, It end) { 4355 //.... 4356 } 4357 4358 false: 4359 template <typename It> 4360 requires Iterator<It> 4361 void sort(It begin, It end) { 4362 //.... 4363 } 4364 4365.. _IndentWidth: 4366 4367**IndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWidth>` 4368 The number of columns to use for indentation. 4369 4370 .. code-block:: c++ 4371 4372 IndentWidth: 3 4373 4374 void f() { 4375 someFunction(); 4376 if (true, false) { 4377 f(); 4378 } 4379 } 4380 4381.. _IndentWrappedFunctionNames: 4382 4383**IndentWrappedFunctionNames** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWrappedFunctionNames>` 4384 Indent if a function definition or declaration is wrapped after the 4385 type. 4386 4387 .. code-block:: c++ 4388 4389 true: 4390 LoooooooooooooooooooooooooooooooooooooooongReturnType 4391 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 4392 4393 false: 4394 LoooooooooooooooooooooooooooooooooooooooongReturnType 4395 LoooooooooooooooooooooooooooooooongFunctionDeclaration(); 4396 4397.. _InsertBraces: 4398 4399**InsertBraces** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <InsertBraces>` 4400 Insert braces after control statements (``if``, ``else``, ``for``, ``do``, 4401 and ``while``) in C++ unless the control statements are inside macro 4402 definitions or the braces would enclose preprocessor directives. 4403 4404 .. warning:: 4405 4406 Setting this option to ``true`` could lead to incorrect code formatting 4407 due to clang-format's lack of complete semantic information. As such, 4408 extra care should be taken to review code changes made by this option. 4409 4410 .. code-block:: c++ 4411 4412 false: true: 4413 4414 if (isa<FunctionDecl>(D)) vs. if (isa<FunctionDecl>(D)) { 4415 handleFunctionDecl(D); handleFunctionDecl(D); 4416 else if (isa<VarDecl>(D)) } else if (isa<VarDecl>(D)) { 4417 handleVarDecl(D); handleVarDecl(D); 4418 else } else { 4419 return; return; 4420 } 4421 4422 while (i--) vs. while (i--) { 4423 for (auto *A : D.attrs()) for (auto *A : D.attrs()) { 4424 handleAttr(A); handleAttr(A); 4425 } 4426 } 4427 4428 do vs. do { 4429 --i; --i; 4430 while (i); } while (i); 4431 4432.. _InsertNewlineAtEOF: 4433 4434**InsertNewlineAtEOF** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <InsertNewlineAtEOF>` 4435 Insert a newline at end of file if missing. 4436 4437.. _InsertTrailingCommas: 4438 4439**InsertTrailingCommas** (``TrailingCommaStyle``) :versionbadge:`clang-format 11` :ref:`¶ <InsertTrailingCommas>` 4440 If set to ``TCS_Wrapped`` will insert trailing commas in container 4441 literals (arrays and objects) that wrap across multiple lines. 4442 It is currently only available for JavaScript 4443 and disabled by default ``TCS_None``. 4444 ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` 4445 as inserting the comma disables bin-packing. 4446 4447 .. code-block:: c++ 4448 4449 TSC_Wrapped: 4450 const someArray = [ 4451 aaaaaaaaaaaaaaaaaaaaaaaaaa, 4452 aaaaaaaaaaaaaaaaaaaaaaaaaa, 4453 aaaaaaaaaaaaaaaaaaaaaaaaaa, 4454 // ^ inserted 4455 ] 4456 4457 Possible values: 4458 4459 * ``TCS_None`` (in configuration: ``None``) 4460 Do not insert trailing commas. 4461 4462 * ``TCS_Wrapped`` (in configuration: ``Wrapped``) 4463 Insert trailing commas in container literals that were wrapped over 4464 multiple lines. Note that this is conceptually incompatible with 4465 bin-packing, because the trailing comma is used as an indicator 4466 that a container should be formatted one-per-line (i.e. not bin-packed). 4467 So inserting a trailing comma counteracts bin-packing. 4468 4469 4470 4471.. _IntegerLiteralSeparator: 4472 4473**IntegerLiteralSeparator** (``IntegerLiteralSeparatorStyle``) :versionbadge:`clang-format 16` :ref:`¶ <IntegerLiteralSeparator>` 4474 Format integer literal separators (``'`` for C++ and ``_`` for C#, Java, 4475 and JavaScript). 4476 4477 Nested configuration flags: 4478 4479 Separator format of integer literals of different bases. 4480 4481 If negative, remove separators. If ``0``, leave the literal as is. If 4482 positive, insert separators between digits starting from the rightmost 4483 digit. 4484 4485 For example, the config below will leave separators in binary literals 4486 alone, insert separators in decimal literals to separate the digits into 4487 groups of 3, and remove separators in hexadecimal literals. 4488 4489 .. code-block:: c++ 4490 4491 IntegerLiteralSeparator: 4492 Binary: 0 4493 Decimal: 3 4494 Hex: -1 4495 4496 You can also specify a minimum number of digits (``BinaryMinDigits``, 4497 ``DecimalMinDigits``, and ``HexMinDigits``) the integer literal must 4498 have in order for the separators to be inserted. 4499 4500 * ``int8_t Binary`` Format separators in binary literals. 4501 4502 .. code-block:: text 4503 4504 /* -1: */ b = 0b100111101101; 4505 /* 0: */ b = 0b10011'11'0110'1; 4506 /* 3: */ b = 0b100'111'101'101; 4507 /* 4: */ b = 0b1001'1110'1101; 4508 4509 * ``int8_t BinaryMinDigits`` Format separators in binary literals with a minimum number of digits. 4510 4511 .. code-block:: text 4512 4513 // Binary: 3 4514 // BinaryMinDigits: 7 4515 b1 = 0b101101; 4516 b2 = 0b1'101'101; 4517 4518 * ``int8_t Decimal`` Format separators in decimal literals. 4519 4520 .. code-block:: text 4521 4522 /* -1: */ d = 18446744073709550592ull; 4523 /* 0: */ d = 184467'440737'0'95505'92ull; 4524 /* 3: */ d = 18'446'744'073'709'550'592ull; 4525 4526 * ``int8_t DecimalMinDigits`` Format separators in decimal literals with a minimum number of digits. 4527 4528 .. code-block:: text 4529 4530 // Decimal: 3 4531 // DecimalMinDigits: 5 4532 d1 = 2023; 4533 d2 = 10'000; 4534 4535 * ``int8_t Hex`` Format separators in hexadecimal literals. 4536 4537 .. code-block:: text 4538 4539 /* -1: */ h = 0xDEADBEEFDEADBEEFuz; 4540 /* 0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz; 4541 /* 2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz; 4542 4543 * ``int8_t HexMinDigits`` Format separators in hexadecimal literals with a minimum number of 4544 digits. 4545 4546 .. code-block:: text 4547 4548 // Hex: 2 4549 // HexMinDigits: 6 4550 h1 = 0xABCDE; 4551 h2 = 0xAB'CD'EF; 4552 4553 4554.. _JavaImportGroups: 4555 4556**JavaImportGroups** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <JavaImportGroups>` 4557 A vector of prefixes ordered by the desired groups for Java imports. 4558 4559 One group's prefix can be a subset of another - the longest prefix is 4560 always matched. Within a group, the imports are ordered lexicographically. 4561 Static imports are grouped separately and follow the same group rules. 4562 By default, static imports are placed before non-static imports, 4563 but this behavior is changed by another option, 4564 ``SortJavaStaticImport``. 4565 4566 In the .clang-format configuration file, this can be configured like 4567 in the following yaml example. This will result in imports being 4568 formatted as in the Java example below. 4569 4570 .. code-block:: yaml 4571 4572 JavaImportGroups: [com.example, com, org] 4573 4574 4575 .. code-block:: java 4576 4577 import static com.example.function1; 4578 4579 import static com.test.function2; 4580 4581 import static org.example.function3; 4582 4583 import com.example.ClassA; 4584 import com.example.Test; 4585 import com.example.a.ClassB; 4586 4587 import com.test.ClassC; 4588 4589 import org.example.ClassD; 4590 4591.. _JavaScriptQuotes: 4592 4593**JavaScriptQuotes** (``JavaScriptQuoteStyle``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptQuotes>` 4594 The JavaScriptQuoteStyle to use for JavaScript strings. 4595 4596 Possible values: 4597 4598 * ``JSQS_Leave`` (in configuration: ``Leave``) 4599 Leave string quotes as they are. 4600 4601 .. code-block:: js 4602 4603 string1 = "foo"; 4604 string2 = 'bar'; 4605 4606 * ``JSQS_Single`` (in configuration: ``Single``) 4607 Always use single quotes. 4608 4609 .. code-block:: js 4610 4611 string1 = 'foo'; 4612 string2 = 'bar'; 4613 4614 * ``JSQS_Double`` (in configuration: ``Double``) 4615 Always use double quotes. 4616 4617 .. code-block:: js 4618 4619 string1 = "foo"; 4620 string2 = "bar"; 4621 4622 4623 4624.. _JavaScriptWrapImports: 4625 4626**JavaScriptWrapImports** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptWrapImports>` 4627 Whether to wrap JavaScript import/export statements. 4628 4629 .. code-block:: js 4630 4631 true: 4632 import { 4633 VeryLongImportsAreAnnoying, 4634 VeryLongImportsAreAnnoying, 4635 VeryLongImportsAreAnnoying, 4636 } from "some/module.js" 4637 4638 false: 4639 import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" 4640 4641.. _KeepEmptyLines: 4642 4643**KeepEmptyLines** (``KeepEmptyLinesStyle``) :versionbadge:`clang-format 19` :ref:`¶ <KeepEmptyLines>` 4644 Which empty lines are kept. See ``MaxEmptyLinesToKeep`` for how many 4645 consecutive empty lines are kept. 4646 4647 Nested configuration flags: 4648 4649 Options regarding which empty lines are kept. 4650 4651 For example, the config below will remove empty lines at start of the 4652 file, end of the file, and start of blocks. 4653 4654 4655 .. code-block:: c++ 4656 4657 KeepEmptyLines: 4658 AtEndOfFile: false 4659 AtStartOfBlock: false 4660 AtStartOfFile: false 4661 4662 * ``bool AtEndOfFile`` Keep empty lines at end of file. 4663 4664 * ``bool AtStartOfBlock`` Keep empty lines at start of a block. 4665 4666 .. code-block:: c++ 4667 4668 true: false: 4669 if (foo) { vs. if (foo) { 4670 bar(); 4671 bar(); } 4672 } 4673 4674 * ``bool AtStartOfFile`` Keep empty lines at start of file. 4675 4676 4677.. _KeepEmptyLinesAtEOF: 4678 4679**KeepEmptyLinesAtEOF** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <KeepEmptyLinesAtEOF>` 4680 This option is **deprecated**. See ``AtEndOfFile`` of ``KeepEmptyLines``. 4681 4682.. _KeepEmptyLinesAtTheStartOfBlocks: 4683 4684**KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <KeepEmptyLinesAtTheStartOfBlocks>` 4685 This option is **deprecated**. See ``AtStartOfBlock`` of 4686 ``KeepEmptyLines``. 4687 4688.. _KeepFormFeed: 4689 4690**KeepFormFeed** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <KeepFormFeed>` 4691 Keep the form feed character if it's immediately preceded and followed by 4692 a newline. Multiple form feeds and newlines within a whitespace range are 4693 replaced with a single newline and form feed followed by the remaining 4694 newlines. 4695 4696.. _LambdaBodyIndentation: 4697 4698**LambdaBodyIndentation** (``LambdaBodyIndentationKind``) :versionbadge:`clang-format 13` :ref:`¶ <LambdaBodyIndentation>` 4699 The indentation style of lambda bodies. ``Signature`` (the default) 4700 causes the lambda body to be indented one additional level relative to 4701 the indentation level of the signature. ``OuterScope`` forces the lambda 4702 body to be indented one additional level relative to the parent scope 4703 containing the lambda signature. 4704 4705 Possible values: 4706 4707 * ``LBI_Signature`` (in configuration: ``Signature``) 4708 Align lambda body relative to the lambda signature. This is the default. 4709 4710 .. code-block:: c++ 4711 4712 someMethod( 4713 [](SomeReallyLongLambdaSignatureArgument foo) { 4714 return; 4715 }); 4716 4717 * ``LBI_OuterScope`` (in configuration: ``OuterScope``) 4718 For statements within block scope, align lambda body relative to the 4719 indentation level of the outer scope the lambda signature resides in. 4720 4721 .. code-block:: c++ 4722 4723 someMethod( 4724 [](SomeReallyLongLambdaSignatureArgument foo) { 4725 return; 4726 }); 4727 4728 someMethod(someOtherMethod( 4729 [](SomeReallyLongLambdaSignatureArgument foo) { 4730 return; 4731 })); 4732 4733 4734 4735.. _Language: 4736 4737**Language** (``LanguageKind``) :versionbadge:`clang-format 3.5` :ref:`¶ <Language>` 4738 Language, this format style is targeted at. 4739 4740 Possible values: 4741 4742 * ``LK_None`` (in configuration: ``None``) 4743 Do not use. 4744 4745 * ``LK_Cpp`` (in configuration: ``Cpp``) 4746 Should be used for C, C++. 4747 4748 * ``LK_CSharp`` (in configuration: ``CSharp``) 4749 Should be used for C#. 4750 4751 * ``LK_Java`` (in configuration: ``Java``) 4752 Should be used for Java. 4753 4754 * ``LK_JavaScript`` (in configuration: ``JavaScript``) 4755 Should be used for JavaScript. 4756 4757 * ``LK_Json`` (in configuration: ``Json``) 4758 Should be used for JSON. 4759 4760 * ``LK_ObjC`` (in configuration: ``ObjC``) 4761 Should be used for Objective-C, Objective-C++. 4762 4763 * ``LK_Proto`` (in configuration: ``Proto``) 4764 Should be used for Protocol Buffers 4765 (https://developers.google.com/protocol-buffers/). 4766 4767 * ``LK_TableGen`` (in configuration: ``TableGen``) 4768 Should be used for TableGen code. 4769 4770 * ``LK_TextProto`` (in configuration: ``TextProto``) 4771 Should be used for Protocol Buffer messages in text format 4772 (https://developers.google.com/protocol-buffers/). 4773 4774 * ``LK_Verilog`` (in configuration: ``Verilog``) 4775 Should be used for Verilog and SystemVerilog. 4776 https://standards.ieee.org/ieee/1800/6700/ 4777 https://sci-hub.st/10.1109/IEEESTD.2018.8299595 4778 4779 4780 4781.. _LineEnding: 4782 4783**LineEnding** (``LineEndingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <LineEnding>` 4784 Line ending style (``\n`` or ``\r\n``) to use. 4785 4786 Possible values: 4787 4788 * ``LE_LF`` (in configuration: ``LF``) 4789 Use ``\n``. 4790 4791 * ``LE_CRLF`` (in configuration: ``CRLF``) 4792 Use ``\r\n``. 4793 4794 * ``LE_DeriveLF`` (in configuration: ``DeriveLF``) 4795 Use ``\n`` unless the input has more lines ending in ``\r\n``. 4796 4797 * ``LE_DeriveCRLF`` (in configuration: ``DeriveCRLF``) 4798 Use ``\r\n`` unless the input has more lines ending in ``\n``. 4799 4800 4801 4802.. _MacroBlockBegin: 4803 4804**MacroBlockBegin** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockBegin>` 4805 A regular expression matching macros that start a block. 4806 4807 .. code-block:: c++ 4808 4809 # With: 4810 MacroBlockBegin: "^NS_MAP_BEGIN|\ 4811 NS_TABLE_HEAD$" 4812 MacroBlockEnd: "^\ 4813 NS_MAP_END|\ 4814 NS_TABLE_.*_END$" 4815 4816 NS_MAP_BEGIN 4817 foo(); 4818 NS_MAP_END 4819 4820 NS_TABLE_HEAD 4821 bar(); 4822 NS_TABLE_FOO_END 4823 4824 # Without: 4825 NS_MAP_BEGIN 4826 foo(); 4827 NS_MAP_END 4828 4829 NS_TABLE_HEAD 4830 bar(); 4831 NS_TABLE_FOO_END 4832 4833.. _MacroBlockEnd: 4834 4835**MacroBlockEnd** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockEnd>` 4836 A regular expression matching macros that end a block. 4837 4838.. _Macros: 4839 4840**Macros** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <Macros>` 4841 A list of macros of the form ``<definition>=<expansion>`` . 4842 4843 Code will be parsed with macros expanded, in order to determine how to 4844 interpret and format the macro arguments. 4845 4846 For example, the code: 4847 4848 .. code-block:: c++ 4849 4850 A(a*b); 4851 4852 will usually be interpreted as a call to a function A, and the 4853 multiplication expression will be formatted as ``a * b``. 4854 4855 If we specify the macro definition: 4856 4857 .. code-block:: yaml 4858 4859 Macros: 4860 - A(x)=x 4861 4862 the code will now be parsed as a declaration of the variable b of type a*, 4863 and formatted as ``a* b`` (depending on pointer-binding rules). 4864 4865 Features and restrictions: 4866 * Both function-like macros and object-like macros are supported. 4867 * Macro arguments must be used exactly once in the expansion. 4868 * No recursive expansion; macros referencing other macros will be 4869 ignored. 4870 * Overloading by arity is supported: for example, given the macro 4871 definitions A=x, A()=y, A(a)=a 4872 4873 4874 .. code-block:: c++ 4875 4876 A; -> x; 4877 A(); -> y; 4878 A(z); -> z; 4879 A(a, b); // will not be expanded. 4880 4881.. _MainIncludeChar: 4882 4883**MainIncludeChar** (``MainIncludeCharDiscriminator``) :versionbadge:`clang-format 19` :ref:`¶ <MainIncludeChar>` 4884 When guessing whether a #include is the "main" include, only the include 4885 directives that use the specified character are considered. 4886 4887 Possible values: 4888 4889 * ``MICD_Quote`` (in configuration: ``Quote``) 4890 Main include uses quotes: ``#include "foo.hpp"`` (the default). 4891 4892 * ``MICD_AngleBracket`` (in configuration: ``AngleBracket``) 4893 Main include uses angle brackets: ``#include <foo.hpp>``. 4894 4895 * ``MICD_Any`` (in configuration: ``Any``) 4896 Main include uses either quotes or angle brackets. 4897 4898 4899 4900.. _MaxEmptyLinesToKeep: 4901 4902**MaxEmptyLinesToKeep** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <MaxEmptyLinesToKeep>` 4903 The maximum number of consecutive empty lines to keep. 4904 4905 .. code-block:: c++ 4906 4907 MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 4908 int f() { int f() { 4909 int = 1; int i = 1; 4910 i = foo(); 4911 i = foo(); return i; 4912 } 4913 return i; 4914 } 4915 4916.. _NamespaceIndentation: 4917 4918**NamespaceIndentation** (``NamespaceIndentationKind``) :versionbadge:`clang-format 3.7` :ref:`¶ <NamespaceIndentation>` 4919 The indentation used for namespaces. 4920 4921 Possible values: 4922 4923 * ``NI_None`` (in configuration: ``None``) 4924 Don't indent in namespaces. 4925 4926 .. code-block:: c++ 4927 4928 namespace out { 4929 int i; 4930 namespace in { 4931 int i; 4932 } 4933 } 4934 4935 * ``NI_Inner`` (in configuration: ``Inner``) 4936 Indent only in inner namespaces (nested in other namespaces). 4937 4938 .. code-block:: c++ 4939 4940 namespace out { 4941 int i; 4942 namespace in { 4943 int i; 4944 } 4945 } 4946 4947 * ``NI_All`` (in configuration: ``All``) 4948 Indent in all namespaces. 4949 4950 .. code-block:: c++ 4951 4952 namespace out { 4953 int i; 4954 namespace in { 4955 int i; 4956 } 4957 } 4958 4959 4960 4961.. _NamespaceMacros: 4962 4963**NamespaceMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <NamespaceMacros>` 4964 A vector of macros which are used to open namespace blocks. 4965 4966 These are expected to be macros of the form: 4967 4968 .. code-block:: c++ 4969 4970 NAMESPACE(<namespace-name>, ...) { 4971 <namespace-content> 4972 } 4973 4974 For example: TESTSUITE 4975 4976.. _ObjCBinPackProtocolList: 4977 4978**ObjCBinPackProtocolList** (``BinPackStyle``) :versionbadge:`clang-format 7` :ref:`¶ <ObjCBinPackProtocolList>` 4979 Controls bin-packing Objective-C protocol conformance list 4980 items into as few lines as possible when they go over ``ColumnLimit``. 4981 4982 If ``Auto`` (the default), delegates to the value in 4983 ``BinPackParameters``. If that is ``BinPack``, bin-packs Objective-C 4984 protocol conformance list items into as few lines as possible 4985 whenever they go over ``ColumnLimit``. 4986 4987 If ``Always``, always bin-packs Objective-C protocol conformance 4988 list items into as few lines as possible whenever they go over 4989 ``ColumnLimit``. 4990 4991 If ``Never``, lays out Objective-C protocol conformance list items 4992 onto individual lines whenever they go over ``ColumnLimit``. 4993 4994 4995 .. code-block:: objc 4996 4997 Always (or Auto, if BinPackParameters==BinPack): 4998 @interface ccccccccccccc () < 4999 ccccccccccccc, ccccccccccccc, 5000 ccccccccccccc, ccccccccccccc> { 5001 } 5002 5003 Never (or Auto, if BinPackParameters!=BinPack): 5004 @interface ddddddddddddd () < 5005 ddddddddddddd, 5006 ddddddddddddd, 5007 ddddddddddddd, 5008 ddddddddddddd> { 5009 } 5010 5011 Possible values: 5012 5013 * ``BPS_Auto`` (in configuration: ``Auto``) 5014 Automatically determine parameter bin-packing behavior. 5015 5016 * ``BPS_Always`` (in configuration: ``Always``) 5017 Always bin-pack parameters. 5018 5019 * ``BPS_Never`` (in configuration: ``Never``) 5020 Never bin-pack parameters. 5021 5022 5023 5024.. _ObjCBlockIndentWidth: 5025 5026**ObjCBlockIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCBlockIndentWidth>` 5027 The number of characters to use for indentation of ObjC blocks. 5028 5029 .. code-block:: objc 5030 5031 ObjCBlockIndentWidth: 4 5032 5033 [operation setCompletionBlock:^{ 5034 [self onOperationDone]; 5035 }]; 5036 5037.. _ObjCBreakBeforeNestedBlockParam: 5038 5039**ObjCBreakBeforeNestedBlockParam** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <ObjCBreakBeforeNestedBlockParam>` 5040 Break parameters list into lines when there is nested block 5041 parameters in a function call. 5042 5043 .. code-block:: c++ 5044 5045 false: 5046 - (void)_aMethod 5047 { 5048 [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber 5049 *u, NSNumber *v) { 5050 u = c; 5051 }] 5052 } 5053 true: 5054 - (void)_aMethod 5055 { 5056 [self.test1 t:self 5057 w:self 5058 callback:^(typeof(self) self, NSNumber *u, NSNumber *v) { 5059 u = c; 5060 }] 5061 } 5062 5063.. _ObjCPropertyAttributeOrder: 5064 5065**ObjCPropertyAttributeOrder** (``List of Strings``) :versionbadge:`clang-format 18` :ref:`¶ <ObjCPropertyAttributeOrder>` 5066 The order in which ObjC property attributes should appear. 5067 5068 Attributes in code will be sorted in the order specified. Any attributes 5069 encountered that are not mentioned in this array will be sorted last, in 5070 stable order. Comments between attributes will leave the attributes 5071 untouched. 5072 5073 .. warning:: 5074 5075 Using this option could lead to incorrect code formatting due to 5076 clang-format's lack of complete semantic information. As such, extra 5077 care should be taken to review code changes made by this option. 5078 5079 .. code-block:: yaml 5080 5081 ObjCPropertyAttributeOrder: [ 5082 class, direct, 5083 atomic, nonatomic, 5084 assign, retain, strong, copy, weak, unsafe_unretained, 5085 readonly, readwrite, getter, setter, 5086 nullable, nonnull, null_resettable, null_unspecified 5087 ] 5088 5089.. _ObjCSpaceAfterProperty: 5090 5091**ObjCSpaceAfterProperty** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceAfterProperty>` 5092 Add a space after ``@property`` in Objective-C, i.e. use 5093 ``@property (readonly)`` instead of ``@property(readonly)``. 5094 5095.. _ObjCSpaceBeforeProtocolList: 5096 5097**ObjCSpaceBeforeProtocolList** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceBeforeProtocolList>` 5098 Add a space in front of an Objective-C protocol list, i.e. use 5099 ``Foo <Protocol>`` instead of ``Foo<Protocol>``. 5100 5101.. _PPIndentWidth: 5102 5103**PPIndentWidth** (``Integer``) :versionbadge:`clang-format 13` :ref:`¶ <PPIndentWidth>` 5104 The number of columns to use for indentation of preprocessor statements. 5105 When set to -1 (default) ``IndentWidth`` is used also for preprocessor 5106 statements. 5107 5108 .. code-block:: c++ 5109 5110 PPIndentWidth: 1 5111 5112 #ifdef __linux__ 5113 # define FOO 5114 #else 5115 # define BAR 5116 #endif 5117 5118.. _PackConstructorInitializers: 5119 5120**PackConstructorInitializers** (``PackConstructorInitializersStyle``) :versionbadge:`clang-format 14` :ref:`¶ <PackConstructorInitializers>` 5121 The pack constructor initializers style to use. 5122 5123 Possible values: 5124 5125 * ``PCIS_Never`` (in configuration: ``Never``) 5126 Always put each constructor initializer on its own line. 5127 5128 .. code-block:: c++ 5129 5130 Constructor() 5131 : a(), 5132 b() 5133 5134 * ``PCIS_BinPack`` (in configuration: ``BinPack``) 5135 Bin-pack constructor initializers. 5136 5137 .. code-block:: c++ 5138 5139 Constructor() 5140 : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), 5141 cccccccccccccccccccc() 5142 5143 * ``PCIS_CurrentLine`` (in configuration: ``CurrentLine``) 5144 Put all constructor initializers on the current line if they fit. 5145 Otherwise, put each one on its own line. 5146 5147 .. code-block:: c++ 5148 5149 Constructor() : a(), b() 5150 5151 Constructor() 5152 : aaaaaaaaaaaaaaaaaaaa(), 5153 bbbbbbbbbbbbbbbbbbbb(), 5154 ddddddddddddd() 5155 5156 * ``PCIS_NextLine`` (in configuration: ``NextLine``) 5157 Same as ``PCIS_CurrentLine`` except that if all constructor initializers 5158 do not fit on the current line, try to fit them on the next line. 5159 5160 .. code-block:: c++ 5161 5162 Constructor() : a(), b() 5163 5164 Constructor() 5165 : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd() 5166 5167 Constructor() 5168 : aaaaaaaaaaaaaaaaaaaa(), 5169 bbbbbbbbbbbbbbbbbbbb(), 5170 cccccccccccccccccccc() 5171 5172 * ``PCIS_NextLineOnly`` (in configuration: ``NextLineOnly``) 5173 Put all constructor initializers on the next line if they fit. 5174 Otherwise, put each one on its own line. 5175 5176 .. code-block:: c++ 5177 5178 Constructor() 5179 : a(), b() 5180 5181 Constructor() 5182 : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd() 5183 5184 Constructor() 5185 : aaaaaaaaaaaaaaaaaaaa(), 5186 bbbbbbbbbbbbbbbbbbbb(), 5187 cccccccccccccccccccc() 5188 5189 5190 5191.. _PenaltyBreakAssignment: 5192 5193**PenaltyBreakAssignment** (``Unsigned``) :versionbadge:`clang-format 5` :ref:`¶ <PenaltyBreakAssignment>` 5194 The penalty for breaking around an assignment operator. 5195 5196.. _PenaltyBreakBeforeFirstCallParameter: 5197 5198**PenaltyBreakBeforeFirstCallParameter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakBeforeFirstCallParameter>` 5199 The penalty for breaking a function call after ``call(``. 5200 5201.. _PenaltyBreakBeforeMemberAccess: 5202 5203**PenaltyBreakBeforeMemberAccess** (``Unsigned``) :versionbadge:`clang-format 20` :ref:`¶ <PenaltyBreakBeforeMemberAccess>` 5204 The penalty for breaking before a member access operator (``.``, ``->``). 5205 5206.. _PenaltyBreakComment: 5207 5208**PenaltyBreakComment** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakComment>` 5209 The penalty for each line break introduced inside a comment. 5210 5211.. _PenaltyBreakFirstLessLess: 5212 5213**PenaltyBreakFirstLessLess** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakFirstLessLess>` 5214 The penalty for breaking before the first ``<<``. 5215 5216.. _PenaltyBreakOpenParenthesis: 5217 5218**PenaltyBreakOpenParenthesis** (``Unsigned``) :versionbadge:`clang-format 14` :ref:`¶ <PenaltyBreakOpenParenthesis>` 5219 The penalty for breaking after ``(``. 5220 5221.. _PenaltyBreakScopeResolution: 5222 5223**PenaltyBreakScopeResolution** (``Unsigned``) :versionbadge:`clang-format 18` :ref:`¶ <PenaltyBreakScopeResolution>` 5224 The penalty for breaking after ``::``. 5225 5226.. _PenaltyBreakString: 5227 5228**PenaltyBreakString** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakString>` 5229 The penalty for each line break introduced inside a string literal. 5230 5231.. _PenaltyBreakTemplateDeclaration: 5232 5233**PenaltyBreakTemplateDeclaration** (``Unsigned``) :versionbadge:`clang-format 7` :ref:`¶ <PenaltyBreakTemplateDeclaration>` 5234 The penalty for breaking after template declaration. 5235 5236.. _PenaltyExcessCharacter: 5237 5238**PenaltyExcessCharacter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyExcessCharacter>` 5239 The penalty for each character outside of the column limit. 5240 5241.. _PenaltyIndentedWhitespace: 5242 5243**PenaltyIndentedWhitespace** (``Unsigned``) :versionbadge:`clang-format 12` :ref:`¶ <PenaltyIndentedWhitespace>` 5244 Penalty for each character of whitespace indentation 5245 (counted relative to leading non-whitespace column). 5246 5247.. _PenaltyReturnTypeOnItsOwnLine: 5248 5249**PenaltyReturnTypeOnItsOwnLine** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyReturnTypeOnItsOwnLine>` 5250 Penalty for putting the return type of a function onto its own line. 5251 5252.. _PointerAlignment: 5253 5254**PointerAlignment** (``PointerAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <PointerAlignment>` 5255 Pointer and reference alignment style. 5256 5257 Possible values: 5258 5259 * ``PAS_Left`` (in configuration: ``Left``) 5260 Align pointer to the left. 5261 5262 .. code-block:: c++ 5263 5264 int* a; 5265 5266 * ``PAS_Right`` (in configuration: ``Right``) 5267 Align pointer to the right. 5268 5269 .. code-block:: c++ 5270 5271 int *a; 5272 5273 * ``PAS_Middle`` (in configuration: ``Middle``) 5274 Align pointer in the middle. 5275 5276 .. code-block:: c++ 5277 5278 int * a; 5279 5280 5281 5282.. _QualifierAlignment: 5283 5284**QualifierAlignment** (``QualifierAlignmentStyle``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierAlignment>` 5285 Different ways to arrange specifiers and qualifiers (e.g. const/volatile). 5286 5287 .. warning:: 5288 5289 Setting ``QualifierAlignment`` to something other than ``Leave``, COULD 5290 lead to incorrect code formatting due to incorrect decisions made due to 5291 clang-formats lack of complete semantic information. 5292 As such extra care should be taken to review code changes made by the use 5293 of this option. 5294 5295 Possible values: 5296 5297 * ``QAS_Leave`` (in configuration: ``Leave``) 5298 Don't change specifiers/qualifiers to either Left or Right alignment 5299 (default). 5300 5301 .. code-block:: c++ 5302 5303 int const a; 5304 const int *a; 5305 5306 * ``QAS_Left`` (in configuration: ``Left``) 5307 Change specifiers/qualifiers to be left-aligned. 5308 5309 .. code-block:: c++ 5310 5311 const int a; 5312 const int *a; 5313 5314 * ``QAS_Right`` (in configuration: ``Right``) 5315 Change specifiers/qualifiers to be right-aligned. 5316 5317 .. code-block:: c++ 5318 5319 int const a; 5320 int const *a; 5321 5322 * ``QAS_Custom`` (in configuration: ``Custom``) 5323 Change specifiers/qualifiers to be aligned based on ``QualifierOrder``. 5324 With: 5325 5326 .. code-block:: yaml 5327 5328 QualifierOrder: [inline, static, type, const] 5329 5330 5331 .. code-block:: c++ 5332 5333 5334 int const a; 5335 int const *a; 5336 5337 5338 5339.. _QualifierOrder: 5340 5341**QualifierOrder** (``List of Strings``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierOrder>` 5342 The order in which the qualifiers appear. 5343 The order is an array that can contain any of the following: 5344 5345 * ``const`` 5346 * ``inline`` 5347 * ``static`` 5348 * ``friend`` 5349 * ``constexpr`` 5350 * ``volatile`` 5351 * ``restrict`` 5352 * ``type`` 5353 5354 5355 .. note:: 5356 5357 It must contain ``type``. 5358 5359 Items to the left of ``type`` will be placed to the left of the type and 5360 aligned in the order supplied. Items to the right of ``type`` will be 5361 placed to the right of the type and aligned in the order supplied. 5362 5363 5364 .. code-block:: yaml 5365 5366 QualifierOrder: [inline, static, type, const, volatile] 5367 5368.. _RawStringFormats: 5369 5370**RawStringFormats** (``List of RawStringFormats``) :versionbadge:`clang-format 6` :ref:`¶ <RawStringFormats>` 5371 Defines hints for detecting supported languages code blocks in raw 5372 strings. 5373 5374 A raw string with a matching delimiter or a matching enclosing function 5375 name will be reformatted assuming the specified language based on the 5376 style for that language defined in the .clang-format file. If no style has 5377 been defined in the .clang-format file for the specific language, a 5378 predefined style given by ``BasedOnStyle`` is used. If ``BasedOnStyle`` is 5379 not found, the formatting is based on ``LLVM`` style. A matching delimiter 5380 takes precedence over a matching enclosing function name for determining 5381 the language of the raw string contents. 5382 5383 If a canonical delimiter is specified, occurrences of other delimiters for 5384 the same language will be updated to the canonical if possible. 5385 5386 There should be at most one specification per language and each delimiter 5387 and enclosing function should not occur in multiple specifications. 5388 5389 To configure this in the .clang-format file, use: 5390 5391 .. code-block:: yaml 5392 5393 RawStringFormats: 5394 - Language: TextProto 5395 Delimiters: 5396 - pb 5397 - proto 5398 EnclosingFunctions: 5399 - PARSE_TEXT_PROTO 5400 BasedOnStyle: google 5401 - Language: Cpp 5402 Delimiters: 5403 - cc 5404 - cpp 5405 BasedOnStyle: LLVM 5406 CanonicalDelimiter: cc 5407 5408.. _ReferenceAlignment: 5409 5410**ReferenceAlignment** (``ReferenceAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <ReferenceAlignment>` 5411 Reference alignment style (overrides ``PointerAlignment`` for 5412 references). 5413 5414 Possible values: 5415 5416 * ``RAS_Pointer`` (in configuration: ``Pointer``) 5417 Align reference like ``PointerAlignment``. 5418 5419 * ``RAS_Left`` (in configuration: ``Left``) 5420 Align reference to the left. 5421 5422 .. code-block:: c++ 5423 5424 int& a; 5425 5426 * ``RAS_Right`` (in configuration: ``Right``) 5427 Align reference to the right. 5428 5429 .. code-block:: c++ 5430 5431 int &a; 5432 5433 * ``RAS_Middle`` (in configuration: ``Middle``) 5434 Align reference in the middle. 5435 5436 .. code-block:: c++ 5437 5438 int & a; 5439 5440 5441 5442.. _ReflowComments: 5443 5444**ReflowComments** (``ReflowCommentsStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <ReflowComments>` 5445 Comment reformatting style. 5446 5447 Possible values: 5448 5449 * ``RCS_Never`` (in configuration: ``Never``) 5450 Leave comments untouched. 5451 5452 .. code-block:: c++ 5453 5454 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 5455 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 5456 /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 5457 * and a misaligned second line */ 5458 5459 * ``RCS_IndentOnly`` (in configuration: ``IndentOnly``) 5460 Only apply indentation rules, moving comments left or right, without 5461 changing formatting inside the comments. 5462 5463 .. code-block:: c++ 5464 5465 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 5466 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */ 5467 /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information 5468 * and a misaligned second line */ 5469 5470 * ``RCS_Always`` (in configuration: ``Always``) 5471 Apply indentation rules and reflow long comments into new lines, trying 5472 to obey the ``ColumnLimit``. 5473 5474 .. code-block:: c++ 5475 5476 // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 5477 // information 5478 /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 5479 * information */ 5480 /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of 5481 * information and a misaligned second line */ 5482 5483 5484 5485.. _RemoveBracesLLVM: 5486 5487**RemoveBracesLLVM** (``Boolean``) :versionbadge:`clang-format 14` :ref:`¶ <RemoveBracesLLVM>` 5488 Remove optional braces of control statements (``if``, ``else``, ``for``, 5489 and ``while``) in C++ according to the LLVM coding style. 5490 5491 .. warning:: 5492 5493 This option will be renamed and expanded to support other styles. 5494 5495 .. warning:: 5496 5497 Setting this option to ``true`` could lead to incorrect code formatting 5498 due to clang-format's lack of complete semantic information. As such, 5499 extra care should be taken to review code changes made by this option. 5500 5501 .. code-block:: c++ 5502 5503 false: true: 5504 5505 if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D)) 5506 handleFunctionDecl(D); handleFunctionDecl(D); 5507 } else if (isa<VarDecl>(D)) { else if (isa<VarDecl>(D)) 5508 handleVarDecl(D); handleVarDecl(D); 5509 } 5510 5511 if (isa<VarDecl>(D)) { vs. if (isa<VarDecl>(D)) { 5512 for (auto *A : D.attrs()) { for (auto *A : D.attrs()) 5513 if (shouldProcessAttr(A)) { if (shouldProcessAttr(A)) 5514 handleAttr(A); handleAttr(A); 5515 } } 5516 } 5517 } 5518 5519 if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D)) 5520 for (auto *A : D.attrs()) { for (auto *A : D.attrs()) 5521 handleAttr(A); handleAttr(A); 5522 } 5523 } 5524 5525 if (auto *D = (T)(D)) { vs. if (auto *D = (T)(D)) { 5526 if (shouldProcess(D)) { if (shouldProcess(D)) 5527 handleVarDecl(D); handleVarDecl(D); 5528 } else { else 5529 markAsIgnored(D); markAsIgnored(D); 5530 } } 5531 } 5532 5533 if (a) { vs. if (a) 5534 b(); b(); 5535 } else { else if (c) 5536 if (c) { d(); 5537 d(); else 5538 } else { e(); 5539 e(); 5540 } 5541 } 5542 5543.. _RemoveEmptyLinesInUnwrappedLines: 5544 5545**RemoveEmptyLinesInUnwrappedLines** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <RemoveEmptyLinesInUnwrappedLines>` 5546 Remove empty lines within unwrapped lines. 5547 5548 .. code-block:: c++ 5549 5550 false: true: 5551 5552 int c vs. int c = a + b; 5553 5554 = a + b; 5555 5556 enum : unsigned vs. enum : unsigned { 5557 AA = 0, 5558 { BB 5559 AA = 0, } myEnum; 5560 BB 5561 } myEnum; 5562 5563 while ( vs. while (true) { 5564 } 5565 true) { 5566 } 5567 5568.. _RemoveParentheses: 5569 5570**RemoveParentheses** (``RemoveParenthesesStyle``) :versionbadge:`clang-format 17` :ref:`¶ <RemoveParentheses>` 5571 Remove redundant parentheses. 5572 5573 .. warning:: 5574 5575 Setting this option to any value other than ``Leave`` could lead to 5576 incorrect code formatting due to clang-format's lack of complete semantic 5577 information. As such, extra care should be taken to review code changes 5578 made by this option. 5579 5580 Possible values: 5581 5582 * ``RPS_Leave`` (in configuration: ``Leave``) 5583 Do not remove parentheses. 5584 5585 .. code-block:: c++ 5586 5587 class __declspec((dllimport)) X {}; 5588 co_return (((0))); 5589 return ((a + b) - ((c + d))); 5590 5591 * ``RPS_MultipleParentheses`` (in configuration: ``MultipleParentheses``) 5592 Replace multiple parentheses with single parentheses. 5593 5594 .. code-block:: c++ 5595 5596 class __declspec(dllimport) X {}; 5597 co_return (0); 5598 return ((a + b) - (c + d)); 5599 5600 * ``RPS_ReturnStatement`` (in configuration: ``ReturnStatement``) 5601 Also remove parentheses enclosing the expression in a 5602 ``return``/``co_return`` statement. 5603 5604 .. code-block:: c++ 5605 5606 class __declspec(dllimport) X {}; 5607 co_return 0; 5608 return (a + b) - (c + d); 5609 5610 5611 5612.. _RemoveSemicolon: 5613 5614**RemoveSemicolon** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <RemoveSemicolon>` 5615 Remove semicolons after the closing braces of functions and 5616 constructors/destructors. 5617 5618 .. warning:: 5619 5620 Setting this option to ``true`` could lead to incorrect code formatting 5621 due to clang-format's lack of complete semantic information. As such, 5622 extra care should be taken to review code changes made by this option. 5623 5624 .. code-block:: c++ 5625 5626 false: true: 5627 5628 int max(int a, int b) { int max(int a, int b) { 5629 return a > b ? a : b; return a > b ? a : b; 5630 }; } 5631 5632.. _RequiresClausePosition: 5633 5634**RequiresClausePosition** (``RequiresClausePositionStyle``) :versionbadge:`clang-format 15` :ref:`¶ <RequiresClausePosition>` 5635 The position of the ``requires`` clause. 5636 5637 Possible values: 5638 5639 * ``RCPS_OwnLine`` (in configuration: ``OwnLine``) 5640 Always put the ``requires`` clause on its own line (possibly followed by 5641 a semicolon). 5642 5643 .. code-block:: c++ 5644 5645 template <typename T> 5646 requires C<T> 5647 struct Foo {... 5648 5649 template <typename T> 5650 void bar(T t) 5651 requires C<T>; 5652 5653 template <typename T> 5654 requires C<T> 5655 void bar(T t) {... 5656 5657 template <typename T> 5658 void baz(T t) 5659 requires C<T> 5660 {... 5661 5662 * ``RCPS_OwnLineWithBrace`` (in configuration: ``OwnLineWithBrace``) 5663 As with ``OwnLine``, except, unless otherwise prohibited, place a 5664 following open brace (of a function definition) to follow on the same 5665 line. 5666 5667 .. code-block:: c++ 5668 5669 void bar(T t) 5670 requires C<T> { 5671 return; 5672 } 5673 5674 void bar(T t) 5675 requires C<T> {} 5676 5677 template <typename T> 5678 requires C<T> 5679 void baz(T t) { 5680 ... 5681 5682 * ``RCPS_WithPreceding`` (in configuration: ``WithPreceding``) 5683 Try to put the clause together with the preceding part of a declaration. 5684 For class templates: stick to the template declaration. 5685 For function templates: stick to the template declaration. 5686 For function declaration followed by a requires clause: stick to the 5687 parameter list. 5688 5689 .. code-block:: c++ 5690 5691 template <typename T> requires C<T> 5692 struct Foo {... 5693 5694 template <typename T> requires C<T> 5695 void bar(T t) {... 5696 5697 template <typename T> 5698 void baz(T t) requires C<T> 5699 {... 5700 5701 * ``RCPS_WithFollowing`` (in configuration: ``WithFollowing``) 5702 Try to put the ``requires`` clause together with the class or function 5703 declaration. 5704 5705 .. code-block:: c++ 5706 5707 template <typename T> 5708 requires C<T> struct Foo {... 5709 5710 template <typename T> 5711 requires C<T> void bar(T t) {... 5712 5713 template <typename T> 5714 void baz(T t) 5715 requires C<T> {... 5716 5717 * ``RCPS_SingleLine`` (in configuration: ``SingleLine``) 5718 Try to put everything in the same line if possible. Otherwise normal 5719 line breaking rules take over. 5720 5721 .. code-block:: c++ 5722 5723 // Fitting: 5724 template <typename T> requires C<T> struct Foo {... 5725 5726 template <typename T> requires C<T> void bar(T t) {... 5727 5728 template <typename T> void bar(T t) requires C<T> {... 5729 5730 // Not fitting, one possible example: 5731 template <typename LongName> 5732 requires C<LongName> 5733 struct Foo {... 5734 5735 template <typename LongName> 5736 requires C<LongName> 5737 void bar(LongName ln) { 5738 5739 template <typename LongName> 5740 void bar(LongName ln) 5741 requires C<LongName> { 5742 5743 5744 5745.. _RequiresExpressionIndentation: 5746 5747**RequiresExpressionIndentation** (``RequiresExpressionIndentationKind``) :versionbadge:`clang-format 16` :ref:`¶ <RequiresExpressionIndentation>` 5748 The indentation used for requires expression bodies. 5749 5750 Possible values: 5751 5752 * ``REI_OuterScope`` (in configuration: ``OuterScope``) 5753 Align requires expression body relative to the indentation level of the 5754 outer scope the requires expression resides in. 5755 This is the default. 5756 5757 .. code-block:: c++ 5758 5759 template <typename T> 5760 concept C = requires(T t) { 5761 ... 5762 } 5763 5764 * ``REI_Keyword`` (in configuration: ``Keyword``) 5765 Align requires expression body relative to the ``requires`` keyword. 5766 5767 .. code-block:: c++ 5768 5769 template <typename T> 5770 concept C = requires(T t) { 5771 ... 5772 } 5773 5774 5775 5776.. _SeparateDefinitionBlocks: 5777 5778**SeparateDefinitionBlocks** (``SeparateDefinitionStyle``) :versionbadge:`clang-format 14` :ref:`¶ <SeparateDefinitionBlocks>` 5779 Specifies the use of empty lines to separate definition blocks, including 5780 classes, structs, enums, and functions. 5781 5782 .. code-block:: c++ 5783 5784 Never v.s. Always 5785 #include <cstring> #include <cstring> 5786 struct Foo { 5787 int a, b, c; struct Foo { 5788 }; int a, b, c; 5789 namespace Ns { }; 5790 class Bar { 5791 public: namespace Ns { 5792 struct Foobar { class Bar { 5793 int a; public: 5794 int b; struct Foobar { 5795 }; int a; 5796 private: int b; 5797 int t; }; 5798 int method1() { 5799 // ... private: 5800 } int t; 5801 enum List { 5802 ITEM1, int method1() { 5803 ITEM2 // ... 5804 }; } 5805 template<typename T> 5806 int method2(T x) { enum List { 5807 // ... ITEM1, 5808 } ITEM2 5809 int i, j, k; }; 5810 int method3(int par) { 5811 // ... template<typename T> 5812 } int method2(T x) { 5813 }; // ... 5814 class C {}; } 5815 } 5816 int i, j, k; 5817 5818 int method3(int par) { 5819 // ... 5820 } 5821 }; 5822 5823 class C {}; 5824 } 5825 5826 Possible values: 5827 5828 * ``SDS_Leave`` (in configuration: ``Leave``) 5829 Leave definition blocks as they are. 5830 5831 * ``SDS_Always`` (in configuration: ``Always``) 5832 Insert an empty line between definition blocks. 5833 5834 * ``SDS_Never`` (in configuration: ``Never``) 5835 Remove any empty line between definition blocks. 5836 5837 5838 5839.. _ShortNamespaceLines: 5840 5841**ShortNamespaceLines** (``Unsigned``) :versionbadge:`clang-format 13` :ref:`¶ <ShortNamespaceLines>` 5842 The maximal number of unwrapped lines that a short namespace spans. 5843 Defaults to 1. 5844 5845 This determines the maximum length of short namespaces by counting 5846 unwrapped lines (i.e. containing neither opening nor closing 5847 namespace brace) and makes ``FixNamespaceComments`` omit adding 5848 end comments for those. 5849 5850 .. code-block:: c++ 5851 5852 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 5853 namespace a { namespace a { 5854 int foo; int foo; 5855 } } // namespace a 5856 5857 ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 5858 namespace b { namespace b { 5859 int foo; int foo; 5860 int bar; int bar; 5861 } // namespace b } // namespace b 5862 5863.. _SkipMacroDefinitionBody: 5864 5865**SkipMacroDefinitionBody** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <SkipMacroDefinitionBody>` 5866 Do not format macro definition body. 5867 5868.. _SortIncludes: 5869 5870**SortIncludes** (``SortIncludesOptions``) :versionbadge:`clang-format 3.8` :ref:`¶ <SortIncludes>` 5871 Controls if and how clang-format will sort ``#includes``. 5872 5873 Possible values: 5874 5875 * ``SI_Never`` (in configuration: ``Never``) 5876 Includes are never sorted. 5877 5878 .. code-block:: c++ 5879 5880 #include "B/A.h" 5881 #include "A/B.h" 5882 #include "a/b.h" 5883 #include "A/b.h" 5884 #include "B/a.h" 5885 5886 * ``SI_CaseSensitive`` (in configuration: ``CaseSensitive``) 5887 Includes are sorted in an ASCIIbetical or case sensitive fashion. 5888 5889 .. code-block:: c++ 5890 5891 #include "A/B.h" 5892 #include "A/b.h" 5893 #include "B/A.h" 5894 #include "B/a.h" 5895 #include "a/b.h" 5896 5897 * ``SI_CaseInsensitive`` (in configuration: ``CaseInsensitive``) 5898 Includes are sorted in an alphabetical or case insensitive fashion. 5899 5900 .. code-block:: c++ 5901 5902 #include "A/B.h" 5903 #include "A/b.h" 5904 #include "a/b.h" 5905 #include "B/A.h" 5906 #include "B/a.h" 5907 5908 5909 5910.. _SortJavaStaticImport: 5911 5912**SortJavaStaticImport** (``SortJavaStaticImportOptions``) :versionbadge:`clang-format 12` :ref:`¶ <SortJavaStaticImport>` 5913 When sorting Java imports, by default static imports are placed before 5914 non-static imports. If ``JavaStaticImportAfterImport`` is ``After``, 5915 static imports are placed after non-static imports. 5916 5917 Possible values: 5918 5919 * ``SJSIO_Before`` (in configuration: ``Before``) 5920 Static imports are placed before non-static imports. 5921 5922 .. code-block:: java 5923 5924 import static org.example.function1; 5925 5926 import org.example.ClassA; 5927 5928 * ``SJSIO_After`` (in configuration: ``After``) 5929 Static imports are placed after non-static imports. 5930 5931 .. code-block:: java 5932 5933 import org.example.ClassA; 5934 5935 import static org.example.function1; 5936 5937 5938 5939.. _SortUsingDeclarations: 5940 5941**SortUsingDeclarations** (``SortUsingDeclarationsOptions``) :versionbadge:`clang-format 5` :ref:`¶ <SortUsingDeclarations>` 5942 Controls if and how clang-format will sort using declarations. 5943 5944 Possible values: 5945 5946 * ``SUD_Never`` (in configuration: ``Never``) 5947 Using declarations are never sorted. 5948 5949 .. code-block:: c++ 5950 5951 using std::chrono::duration_cast; 5952 using std::move; 5953 using boost::regex; 5954 using boost::regex_constants::icase; 5955 using std::string; 5956 5957 * ``SUD_Lexicographic`` (in configuration: ``Lexicographic``) 5958 Using declarations are sorted in the order defined as follows: 5959 Split the strings by ``::`` and discard any initial empty strings. Sort 5960 the lists of names lexicographically, and within those groups, names are 5961 in case-insensitive lexicographic order. 5962 5963 .. code-block:: c++ 5964 5965 using boost::regex; 5966 using boost::regex_constants::icase; 5967 using std::chrono::duration_cast; 5968 using std::move; 5969 using std::string; 5970 5971 * ``SUD_LexicographicNumeric`` (in configuration: ``LexicographicNumeric``) 5972 Using declarations are sorted in the order defined as follows: 5973 Split the strings by ``::`` and discard any initial empty strings. The 5974 last element of each list is a non-namespace name; all others are 5975 namespace names. Sort the lists of names lexicographically, where the 5976 sort order of individual names is that all non-namespace names come 5977 before all namespace names, and within those groups, names are in 5978 case-insensitive lexicographic order. 5979 5980 .. code-block:: c++ 5981 5982 using boost::regex; 5983 using boost::regex_constants::icase; 5984 using std::move; 5985 using std::string; 5986 using std::chrono::duration_cast; 5987 5988 5989 5990.. _SpaceAfterCStyleCast: 5991 5992**SpaceAfterCStyleCast** (``Boolean``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceAfterCStyleCast>` 5993 If ``true``, a space is inserted after C style casts. 5994 5995 .. code-block:: c++ 5996 5997 true: false: 5998 (int) i; vs. (int)i; 5999 6000.. _SpaceAfterLogicalNot: 6001 6002**SpaceAfterLogicalNot** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <SpaceAfterLogicalNot>` 6003 If ``true``, a space is inserted after the logical not operator (``!``). 6004 6005 .. code-block:: c++ 6006 6007 true: false: 6008 ! someExpression(); vs. !someExpression(); 6009 6010.. _SpaceAfterTemplateKeyword: 6011 6012**SpaceAfterTemplateKeyword** (``Boolean``) :versionbadge:`clang-format 4` :ref:`¶ <SpaceAfterTemplateKeyword>` 6013 If ``true``, a space will be inserted after the ``template`` keyword. 6014 6015 .. code-block:: c++ 6016 6017 true: false: 6018 template <int> void foo(); vs. template<int> void foo(); 6019 6020.. _SpaceAroundPointerQualifiers: 6021 6022**SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceAroundPointerQualifiers>` 6023 Defines in which cases to put a space before or after pointer qualifiers 6024 6025 Possible values: 6026 6027 * ``SAPQ_Default`` (in configuration: ``Default``) 6028 Don't ensure spaces around pointer qualifiers and use PointerAlignment 6029 instead. 6030 6031 .. code-block:: c++ 6032 6033 PointerAlignment: Left PointerAlignment: Right 6034 void* const* x = NULL; vs. void *const *x = NULL; 6035 6036 * ``SAPQ_Before`` (in configuration: ``Before``) 6037 Ensure that there is a space before pointer qualifiers. 6038 6039 .. code-block:: c++ 6040 6041 PointerAlignment: Left PointerAlignment: Right 6042 void* const* x = NULL; vs. void * const *x = NULL; 6043 6044 * ``SAPQ_After`` (in configuration: ``After``) 6045 Ensure that there is a space after pointer qualifiers. 6046 6047 .. code-block:: c++ 6048 6049 PointerAlignment: Left PointerAlignment: Right 6050 void* const * x = NULL; vs. void *const *x = NULL; 6051 6052 * ``SAPQ_Both`` (in configuration: ``Both``) 6053 Ensure that there is a space both before and after pointer qualifiers. 6054 6055 .. code-block:: c++ 6056 6057 PointerAlignment: Left PointerAlignment: Right 6058 void* const * x = NULL; vs. void * const *x = NULL; 6059 6060 6061 6062.. _SpaceBeforeAssignmentOperators: 6063 6064**SpaceBeforeAssignmentOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceBeforeAssignmentOperators>` 6065 If ``false``, spaces will be removed before assignment operators. 6066 6067 .. code-block:: c++ 6068 6069 true: false: 6070 int a = 5; vs. int a= 5; 6071 a += 42; a+= 42; 6072 6073.. _SpaceBeforeCaseColon: 6074 6075**SpaceBeforeCaseColon** (``Boolean``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceBeforeCaseColon>` 6076 If ``false``, spaces will be removed before case colon. 6077 6078 .. code-block:: c++ 6079 6080 true: false 6081 switch (x) { vs. switch (x) { 6082 case 1 : break; case 1: break; 6083 } } 6084 6085.. _SpaceBeforeCpp11BracedList: 6086 6087**SpaceBeforeCpp11BracedList** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCpp11BracedList>` 6088 If ``true``, a space will be inserted before a C++11 braced list 6089 used to initialize an object (after the preceding identifier or type). 6090 6091 .. code-block:: c++ 6092 6093 true: false: 6094 Foo foo { bar }; vs. Foo foo{ bar }; 6095 Foo {}; Foo{}; 6096 vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; 6097 new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; 6098 6099.. _SpaceBeforeCtorInitializerColon: 6100 6101**SpaceBeforeCtorInitializerColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCtorInitializerColon>` 6102 If ``false``, spaces will be removed before constructor initializer 6103 colon. 6104 6105 .. code-block:: c++ 6106 6107 true: false: 6108 Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} 6109 6110.. _SpaceBeforeInheritanceColon: 6111 6112**SpaceBeforeInheritanceColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeInheritanceColon>` 6113 If ``false``, spaces will be removed before inheritance colon. 6114 6115 .. code-block:: c++ 6116 6117 true: false: 6118 class Foo : Bar {} vs. class Foo: Bar {} 6119 6120.. _SpaceBeforeJsonColon: 6121 6122**SpaceBeforeJsonColon** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <SpaceBeforeJsonColon>` 6123 If ``true``, a space will be added before a JSON colon. For other 6124 languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead. 6125 6126 .. code-block:: c++ 6127 6128 true: false: 6129 { { 6130 "key" : "value" vs. "key": "value" 6131 } } 6132 6133.. _SpaceBeforeParens: 6134 6135**SpaceBeforeParens** (``SpaceBeforeParensStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceBeforeParens>` 6136 Defines in which cases to put a space before opening parentheses. 6137 6138 Possible values: 6139 6140 * ``SBPO_Never`` (in configuration: ``Never``) 6141 This is **deprecated** and replaced by ``Custom`` below, with all 6142 ``SpaceBeforeParensOptions`` but ``AfterPlacementOperator`` set to 6143 ``false``. 6144 6145 * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``) 6146 Put a space before opening parentheses only after control statement 6147 keywords (``for/if/while...``). 6148 6149 .. code-block:: c++ 6150 6151 void f() { 6152 if (true) { 6153 f(); 6154 } 6155 } 6156 6157 * ``SBPO_ControlStatementsExceptControlMacros`` (in configuration: ``ControlStatementsExceptControlMacros``) 6158 Same as ``SBPO_ControlStatements`` except this option doesn't apply to 6159 ForEach and If macros. This is useful in projects where ForEach/If 6160 macros are treated as function calls instead of control statements. 6161 ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for 6162 backward compatibility. 6163 6164 .. code-block:: c++ 6165 6166 void f() { 6167 Q_FOREACH(...) { 6168 f(); 6169 } 6170 } 6171 6172 * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``) 6173 Put a space before opening parentheses only if the parentheses are not 6174 empty. 6175 6176 .. code-block:: c++ 6177 6178 void() { 6179 if (true) { 6180 f(); 6181 g (x, y, z); 6182 } 6183 } 6184 6185 * ``SBPO_Always`` (in configuration: ``Always``) 6186 Always put a space before opening parentheses, except when it's 6187 prohibited by the syntax rules (in function-like macro definitions) or 6188 when determined by other style rules (after unary operators, opening 6189 parentheses, etc.) 6190 6191 .. code-block:: c++ 6192 6193 void f () { 6194 if (true) { 6195 f (); 6196 } 6197 } 6198 6199 * ``SBPO_Custom`` (in configuration: ``Custom``) 6200 Configure each individual space before parentheses in 6201 ``SpaceBeforeParensOptions``. 6202 6203 6204 6205.. _SpaceBeforeParensOptions: 6206 6207**SpaceBeforeParensOptions** (``SpaceBeforeParensCustom``) :versionbadge:`clang-format 14` :ref:`¶ <SpaceBeforeParensOptions>` 6208 Control of individual space before parentheses. 6209 6210 If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify 6211 how each individual space before parentheses case should be handled. 6212 Otherwise, this is ignored. 6213 6214 .. code-block:: yaml 6215 6216 # Example of usage: 6217 SpaceBeforeParens: Custom 6218 SpaceBeforeParensOptions: 6219 AfterControlStatements: true 6220 AfterFunctionDefinitionName: true 6221 6222 Nested configuration flags: 6223 6224 Precise control over the spacing before parentheses. 6225 6226 .. code-block:: c++ 6227 6228 # Should be declared this way: 6229 SpaceBeforeParens: Custom 6230 SpaceBeforeParensOptions: 6231 AfterControlStatements: true 6232 AfterFunctionDefinitionName: true 6233 6234 * ``bool AfterControlStatements`` If ``true``, put space between control statement keywords 6235 (for/if/while...) and opening parentheses. 6236 6237 .. code-block:: c++ 6238 6239 true: false: 6240 if (...) {} vs. if(...) {} 6241 6242 * ``bool AfterForeachMacros`` If ``true``, put space between foreach macros and opening parentheses. 6243 6244 .. code-block:: c++ 6245 6246 true: false: 6247 FOREACH (...) vs. FOREACH(...) 6248 <loop-body> <loop-body> 6249 6250 * ``bool AfterFunctionDeclarationName`` If ``true``, put a space between function declaration name and opening 6251 parentheses. 6252 6253 .. code-block:: c++ 6254 6255 true: false: 6256 void f (); vs. void f(); 6257 6258 * ``bool AfterFunctionDefinitionName`` If ``true``, put a space between function definition name and opening 6259 parentheses. 6260 6261 .. code-block:: c++ 6262 6263 true: false: 6264 void f () {} vs. void f() {} 6265 6266 * ``bool AfterIfMacros`` If ``true``, put space between if macros and opening parentheses. 6267 6268 .. code-block:: c++ 6269 6270 true: false: 6271 IF (...) vs. IF(...) 6272 <conditional-body> <conditional-body> 6273 6274 * ``bool AfterOverloadedOperator`` If ``true``, put a space between operator overloading and opening 6275 parentheses. 6276 6277 .. code-block:: c++ 6278 6279 true: false: 6280 void operator++ (int a); vs. void operator++(int a); 6281 object.operator++ (10); object.operator++(10); 6282 6283 * ``bool AfterPlacementOperator`` If ``true``, put a space between operator ``new``/``delete`` and opening 6284 parenthesis. 6285 6286 .. code-block:: c++ 6287 6288 true: false: 6289 new (buf) T; vs. new(buf) T; 6290 delete (buf) T; delete(buf) T; 6291 6292 * ``bool AfterRequiresInClause`` If ``true``, put space between requires keyword in a requires clause and 6293 opening parentheses, if there is one. 6294 6295 .. code-block:: c++ 6296 6297 true: false: 6298 template<typename T> vs. template<typename T> 6299 requires (A<T> && B<T>) requires(A<T> && B<T>) 6300 ... ... 6301 6302 * ``bool AfterRequiresInExpression`` If ``true``, put space between requires keyword in a requires expression 6303 and opening parentheses. 6304 6305 .. code-block:: c++ 6306 6307 true: false: 6308 template<typename T> vs. template<typename T> 6309 concept C = requires (T t) { concept C = requires(T t) { 6310 ... ... 6311 } } 6312 6313 * ``bool BeforeNonEmptyParentheses`` If ``true``, put a space before opening parentheses only if the 6314 parentheses are not empty. 6315 6316 .. code-block:: c++ 6317 6318 true: false: 6319 void f (int a); vs. void f(); 6320 f (a); f(); 6321 6322 6323.. _SpaceBeforeRangeBasedForLoopColon: 6324 6325**SpaceBeforeRangeBasedForLoopColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeRangeBasedForLoopColon>` 6326 If ``false``, spaces will be removed before range-based for loop 6327 colon. 6328 6329 .. code-block:: c++ 6330 6331 true: false: 6332 for (auto v : values) {} vs. for(auto v: values) {} 6333 6334.. _SpaceBeforeSquareBrackets: 6335 6336**SpaceBeforeSquareBrackets** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceBeforeSquareBrackets>` 6337 If ``true``, spaces will be before ``[``. 6338 Lambdas will not be affected. Only the first ``[`` will get a space added. 6339 6340 .. code-block:: c++ 6341 6342 true: false: 6343 int a [5]; vs. int a[5]; 6344 int a [5][5]; vs. int a[5][5]; 6345 6346.. _SpaceInEmptyBlock: 6347 6348**SpaceInEmptyBlock** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceInEmptyBlock>` 6349 If ``true``, spaces will be inserted into ``{}``. 6350 6351 .. code-block:: c++ 6352 6353 true: false: 6354 void f() { } vs. void f() {} 6355 while (true) { } while (true) {} 6356 6357.. _SpaceInEmptyParentheses: 6358 6359**SpaceInEmptyParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceInEmptyParentheses>` 6360 If ``true``, spaces may be inserted into ``()``. 6361 This option is **deprecated**. See ``InEmptyParentheses`` of 6362 ``SpacesInParensOptions``. 6363 6364.. _SpacesBeforeTrailingComments: 6365 6366**SpacesBeforeTrailingComments** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesBeforeTrailingComments>` 6367 The number of spaces before trailing line comments 6368 (``//`` - comments). 6369 6370 This does not affect trailing block comments (``/*`` - comments) as those 6371 commonly have different usage patterns and a number of special cases. In 6372 the case of Verilog, it doesn't affect a comment right after the opening 6373 parenthesis in the port or parameter list in a module header, because it 6374 is probably for the port on the following line instead of the parenthesis 6375 it follows. 6376 6377 .. code-block:: c++ 6378 6379 SpacesBeforeTrailingComments: 3 6380 void f() { 6381 if (true) { // foo1 6382 f(); // bar 6383 } // foo 6384 } 6385 6386.. _SpacesInAngles: 6387 6388**SpacesInAngles** (``SpacesInAnglesStyle``) :versionbadge:`clang-format 3.4` :ref:`¶ <SpacesInAngles>` 6389 The SpacesInAnglesStyle to use for template argument lists. 6390 6391 Possible values: 6392 6393 * ``SIAS_Never`` (in configuration: ``Never``) 6394 Remove spaces after ``<`` and before ``>``. 6395 6396 .. code-block:: c++ 6397 6398 static_cast<int>(arg); 6399 std::function<void(int)> fct; 6400 6401 * ``SIAS_Always`` (in configuration: ``Always``) 6402 Add spaces after ``<`` and before ``>``. 6403 6404 .. code-block:: c++ 6405 6406 static_cast< int >(arg); 6407 std::function< void(int) > fct; 6408 6409 * ``SIAS_Leave`` (in configuration: ``Leave``) 6410 Keep a single space after ``<`` and before ``>`` if any spaces were 6411 present. Option ``Standard: Cpp03`` takes precedence. 6412 6413 6414 6415.. _SpacesInCStyleCastParentheses: 6416 6417**SpacesInCStyleCastParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInCStyleCastParentheses>` 6418 If ``true``, spaces may be inserted into C style casts. 6419 This option is **deprecated**. See ``InCStyleCasts`` of 6420 ``SpacesInParensOptions``. 6421 6422.. _SpacesInConditionalStatement: 6423 6424**SpacesInConditionalStatement** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpacesInConditionalStatement>` 6425 If ``true``, spaces will be inserted around if/for/switch/while 6426 conditions. 6427 This option is **deprecated**. See ``InConditionalStatements`` of 6428 ``SpacesInParensOptions``. 6429 6430.. _SpacesInContainerLiterals: 6431 6432**SpacesInContainerLiterals** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInContainerLiterals>` 6433 If ``true``, spaces are inserted inside container literals (e.g. ObjC and 6434 Javascript array and dict literals). For JSON, use 6435 ``SpaceBeforeJsonColon`` instead. 6436 6437 .. code-block:: js 6438 6439 true: false: 6440 var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; 6441 f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); 6442 6443.. _SpacesInLineCommentPrefix: 6444 6445**SpacesInLineCommentPrefix** (``SpacesInLineComment``) :versionbadge:`clang-format 13` :ref:`¶ <SpacesInLineCommentPrefix>` 6446 How many spaces are allowed at the start of a line comment. To disable the 6447 maximum set it to ``-1``, apart from that the maximum takes precedence 6448 over the minimum. 6449 6450 .. code-block:: c++ 6451 6452 Minimum = 1 6453 Maximum = -1 6454 // One space is forced 6455 6456 // but more spaces are possible 6457 6458 Minimum = 0 6459 Maximum = 0 6460 //Forces to start every comment directly after the slashes 6461 6462 Note that in line comment sections the relative indent of the subsequent 6463 lines is kept, that means the following: 6464 6465 .. code-block:: c++ 6466 6467 before: after: 6468 Minimum: 1 6469 //if (b) { // if (b) { 6470 // return true; // return true; 6471 //} // } 6472 6473 Maximum: 0 6474 /// List: ///List: 6475 /// - Foo /// - Foo 6476 /// - Bar /// - Bar 6477 6478 This option has only effect if ``ReflowComments`` is set to ``true``. 6479 6480 Nested configuration flags: 6481 6482 Control of spaces within a single line comment. 6483 6484 * ``unsigned Minimum`` The minimum number of spaces at the start of the comment. 6485 6486 * ``unsigned Maximum`` The maximum number of spaces at the start of the comment. 6487 6488 6489.. _SpacesInParens: 6490 6491**SpacesInParens** (``SpacesInParensStyle``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParens>` 6492 Defines in which cases spaces will be inserted after ``(`` and before 6493 ``)``. 6494 6495 Possible values: 6496 6497 * ``SIPO_Never`` (in configuration: ``Never``) 6498 Never put a space in parentheses. 6499 6500 .. code-block:: c++ 6501 6502 void f() { 6503 if(true) { 6504 f(); 6505 } 6506 } 6507 6508 * ``SIPO_Custom`` (in configuration: ``Custom``) 6509 Configure each individual space in parentheses in 6510 `SpacesInParensOptions`. 6511 6512 6513 6514.. _SpacesInParensOptions: 6515 6516**SpacesInParensOptions** (``SpacesInParensCustom``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParensOptions>` 6517 Control of individual spaces in parentheses. 6518 6519 If ``SpacesInParens`` is set to ``Custom``, use this to specify 6520 how each individual space in parentheses case should be handled. 6521 Otherwise, this is ignored. 6522 6523 .. code-block:: yaml 6524 6525 # Example of usage: 6526 SpacesInParens: Custom 6527 SpacesInParensOptions: 6528 ExceptDoubleParentheses: false 6529 InConditionalStatements: true 6530 InEmptyParentheses: true 6531 6532 Nested configuration flags: 6533 6534 Precise control over the spacing in parentheses. 6535 6536 .. code-block:: c++ 6537 6538 # Should be declared this way: 6539 SpacesInParens: Custom 6540 SpacesInParensOptions: 6541 ExceptDoubleParentheses: false 6542 InConditionalStatements: true 6543 Other: true 6544 6545 * ``bool ExceptDoubleParentheses`` Override any of the following options to prevent addition of space 6546 when both opening and closing parentheses use multiple parentheses. 6547 6548 .. code-block:: c++ 6549 6550 true: 6551 __attribute__(( noreturn )) 6552 __decltype__(( x )) 6553 if (( a = b )) 6554 false: 6555 Uses the applicable option. 6556 6557 * ``bool InConditionalStatements`` Put a space in parentheses only inside conditional statements 6558 (``for/if/while/switch...``). 6559 6560 .. code-block:: c++ 6561 6562 true: false: 6563 if ( a ) { ... } vs. if (a) { ... } 6564 while ( i < 5 ) { ... } while (i < 5) { ... } 6565 6566 * ``bool InCStyleCasts`` Put a space in C style casts. 6567 6568 .. code-block:: c++ 6569 6570 true: false: 6571 x = ( int32 )y vs. x = (int32)y 6572 y = (( int (*)(int) )foo)(x); y = ((int (*)(int))foo)(x); 6573 6574 * ``bool InEmptyParentheses`` Insert a space in empty parentheses, i.e. ``()``. 6575 6576 .. code-block:: c++ 6577 6578 true: false: 6579 void f( ) { vs. void f() { 6580 int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; 6581 if (true) { if (true) { 6582 f( ); f(); 6583 } } 6584 } } 6585 6586 * ``bool Other`` Put a space in parentheses not covered by preceding options. 6587 6588 .. code-block:: c++ 6589 6590 true: false: 6591 t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; 6592 6593 6594.. _SpacesInParentheses: 6595 6596**SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInParentheses>` 6597 If ``true``, spaces will be inserted after ``(`` and before ``)``. 6598 This option is **deprecated**. The previous behavior is preserved by using 6599 ``SpacesInParens`` with ``Custom`` and by setting all 6600 ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and 6601 ``InEmptyParentheses``. 6602 6603.. _SpacesInSquareBrackets: 6604 6605**SpacesInSquareBrackets** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInSquareBrackets>` 6606 If ``true``, spaces will be inserted after ``[`` and before ``]``. 6607 Lambdas without arguments or unspecified size array declarations will not 6608 be affected. 6609 6610 .. code-block:: c++ 6611 6612 true: false: 6613 int a[ 5 ]; vs. int a[5]; 6614 std::unique_ptr<int[]> foo() {} // Won't be affected 6615 6616.. _Standard: 6617 6618**Standard** (``LanguageStandard``) :versionbadge:`clang-format 3.7` :ref:`¶ <Standard>` 6619 Parse and format C++ constructs compatible with this standard. 6620 6621 .. code-block:: c++ 6622 6623 c++03: latest: 6624 vector<set<int> > x; vs. vector<set<int>> x; 6625 6626 Possible values: 6627 6628 * ``LS_Cpp03`` (in configuration: ``c++03``) 6629 Parse and format as C++03. 6630 ``Cpp03`` is a deprecated alias for ``c++03`` 6631 6632 * ``LS_Cpp11`` (in configuration: ``c++11``) 6633 Parse and format as C++11. 6634 6635 * ``LS_Cpp14`` (in configuration: ``c++14``) 6636 Parse and format as C++14. 6637 6638 * ``LS_Cpp17`` (in configuration: ``c++17``) 6639 Parse and format as C++17. 6640 6641 * ``LS_Cpp20`` (in configuration: ``c++20``) 6642 Parse and format as C++20. 6643 6644 * ``LS_Latest`` (in configuration: ``Latest``) 6645 Parse and format using the latest supported language version. 6646 ``Cpp11`` is a deprecated alias for ``Latest`` 6647 6648 * ``LS_Auto`` (in configuration: ``Auto``) 6649 Automatic detection based on the input. 6650 6651 6652 6653.. _StatementAttributeLikeMacros: 6654 6655**StatementAttributeLikeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <StatementAttributeLikeMacros>` 6656 Macros which are ignored in front of a statement, as if they were an 6657 attribute. So that they are not parsed as identifier, for example for Qts 6658 emit. 6659 6660 .. code-block:: c++ 6661 6662 AlignConsecutiveDeclarations: true 6663 StatementAttributeLikeMacros: [] 6664 unsigned char data = 'x'; 6665 emit signal(data); // This is parsed as variable declaration. 6666 6667 AlignConsecutiveDeclarations: true 6668 StatementAttributeLikeMacros: [emit] 6669 unsigned char data = 'x'; 6670 emit signal(data); // Now it's fine again. 6671 6672.. _StatementMacros: 6673 6674**StatementMacros** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <StatementMacros>` 6675 A vector of macros that should be interpreted as complete statements. 6676 6677 Typical macros are expressions and require a semicolon to be added. 6678 Sometimes this is not the case, and this allows to make clang-format aware 6679 of such cases. 6680 6681 For example: Q_UNUSED 6682 6683.. _TabWidth: 6684 6685**TabWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <TabWidth>` 6686 The number of columns used for tab stops. 6687 6688.. _TableGenBreakInsideDAGArg: 6689 6690**TableGenBreakInsideDAGArg** (``DAGArgStyle``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakInsideDAGArg>` 6691 The styles of the line break inside the DAGArg in TableGen. 6692 6693 Possible values: 6694 6695 * ``DAS_DontBreak`` (in configuration: ``DontBreak``) 6696 Never break inside DAGArg. 6697 6698 .. code-block:: c++ 6699 6700 let DAGArgIns = (ins i32:$src1, i32:$src2); 6701 6702 * ``DAS_BreakElements`` (in configuration: ``BreakElements``) 6703 Break inside DAGArg after each list element but for the last. 6704 This aligns to the first element. 6705 6706 .. code-block:: c++ 6707 6708 let DAGArgIns = (ins i32:$src1, 6709 i32:$src2); 6710 6711 * ``DAS_BreakAll`` (in configuration: ``BreakAll``) 6712 Break inside DAGArg after the operator and the all elements. 6713 6714 .. code-block:: c++ 6715 6716 let DAGArgIns = (ins 6717 i32:$src1, 6718 i32:$src2 6719 ); 6720 6721 6722 6723.. _TableGenBreakingDAGArgOperators: 6724 6725**TableGenBreakingDAGArgOperators** (``List of Strings``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakingDAGArgOperators>` 6726 Works only when TableGenBreakInsideDAGArg is not DontBreak. 6727 The string list needs to consist of identifiers in TableGen. 6728 If any identifier is specified, this limits the line breaks by 6729 TableGenBreakInsideDAGArg option only on DAGArg values beginning with 6730 the specified identifiers. 6731 6732 For example the configuration, 6733 6734 .. code-block:: yaml 6735 6736 TableGenBreakInsideDAGArg: BreakAll 6737 TableGenBreakingDAGArgOperators: [ins, outs] 6738 6739 makes the line break only occurs inside DAGArgs beginning with the 6740 specified identifiers ``ins`` and ``outs``. 6741 6742 6743 .. code-block:: c++ 6744 6745 let DAGArgIns = (ins 6746 i32:$src1, 6747 i32:$src2 6748 ); 6749 let DAGArgOtherID = (other i32:$other1, i32:$other2); 6750 let DAGArgBang = (!cast<SomeType>("Some") i32:$src1, i32:$src2) 6751 6752.. _TemplateNames: 6753 6754**TemplateNames** (``List of Strings``) :versionbadge:`clang-format 20` :ref:`¶ <TemplateNames>` 6755 A vector of non-keyword identifiers that should be interpreted as template 6756 names. 6757 6758 A ``<`` after a template name is annotated as a template opener instead of 6759 a binary operator. 6760 6761.. _TypeNames: 6762 6763**TypeNames** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <TypeNames>` 6764 A vector of non-keyword identifiers that should be interpreted as type 6765 names. 6766 6767 A ``*``, ``&``, or ``&&`` between a type name and another non-keyword 6768 identifier is annotated as a pointer or reference token instead of a 6769 binary operator. 6770 6771.. _TypenameMacros: 6772 6773**TypenameMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <TypenameMacros>` 6774 A vector of macros that should be interpreted as type declarations 6775 instead of as function calls. 6776 6777 These are expected to be macros of the form: 6778 6779 .. code-block:: c++ 6780 6781 STACK_OF(...) 6782 6783 In the .clang-format configuration file, this can be configured like: 6784 6785 .. code-block:: yaml 6786 6787 TypenameMacros: [STACK_OF, LIST] 6788 6789 For example: OpenSSL STACK_OF, BSD LIST_ENTRY. 6790 6791.. _UseCRLF: 6792 6793**UseCRLF** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <UseCRLF>` 6794 This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``. 6795 6796.. _UseTab: 6797 6798**UseTab** (``UseTabStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <UseTab>` 6799 The way to use tab characters in the resulting file. 6800 6801 Possible values: 6802 6803 * ``UT_Never`` (in configuration: ``Never``) 6804 Never use tab. 6805 6806 * ``UT_ForIndentation`` (in configuration: ``ForIndentation``) 6807 Use tabs only for indentation. 6808 6809 * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``) 6810 Fill all leading whitespace with tabs, and use spaces for alignment that 6811 appears within a line (e.g. consecutive assignments and declarations). 6812 6813 * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``) 6814 Use tabs for line continuation and indentation, and spaces for 6815 alignment. 6816 6817 * ``UT_Always`` (in configuration: ``Always``) 6818 Use tabs whenever we need to fill whitespace that spans at least from 6819 one tab stop to the next one. 6820 6821 6822 6823.. _VariableTemplates: 6824 6825**VariableTemplates** (``List of Strings``) :versionbadge:`clang-format 20` :ref:`¶ <VariableTemplates>` 6826 A vector of non-keyword identifiers that should be interpreted as variable 6827 template names. 6828 6829 A ``)`` after a variable template instantiation is **not** annotated as 6830 the closing parenthesis of C-style cast operator. 6831 6832.. _VerilogBreakBetweenInstancePorts: 6833 6834**VerilogBreakBetweenInstancePorts** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <VerilogBreakBetweenInstancePorts>` 6835 For Verilog, put each port on its own line in module instantiations. 6836 6837 .. code-block:: c++ 6838 6839 true: 6840 ffnand ff1(.q(), 6841 .qbar(out1), 6842 .clear(in1), 6843 .preset(in2)); 6844 6845 false: 6846 ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2)); 6847 6848.. _WhitespaceSensitiveMacros: 6849 6850**WhitespaceSensitiveMacros** (``List of Strings``) :versionbadge:`clang-format 11` :ref:`¶ <WhitespaceSensitiveMacros>` 6851 A vector of macros which are whitespace-sensitive and should not 6852 be touched. 6853 6854 These are expected to be macros of the form: 6855 6856 .. code-block:: c++ 6857 6858 STRINGIZE(...) 6859 6860 In the .clang-format configuration file, this can be configured like: 6861 6862 .. code-block:: yaml 6863 6864 WhitespaceSensitiveMacros: [STRINGIZE, PP_STRINGIZE] 6865 6866 For example: BOOST_PP_STRINGIZE 6867 6868.. _WrapNamespaceBodyWithEmptyLines: 6869 6870**WrapNamespaceBodyWithEmptyLines** (``WrapNamespaceBodyWithEmptyLinesStyle``) :versionbadge:`clang-format 20` :ref:`¶ <WrapNamespaceBodyWithEmptyLines>` 6871 Wrap namespace body with empty lines. 6872 6873 Possible values: 6874 6875 * ``WNBWELS_Never`` (in configuration: ``Never``) 6876 Remove all empty lines at the beginning and the end of namespace body. 6877 6878 .. code-block:: c++ 6879 6880 namespace N1 { 6881 namespace N2 6882 function(); 6883 } 6884 } 6885 6886 * ``WNBWELS_Always`` (in configuration: ``Always``) 6887 Always have at least one empty line at the beginning and the end of 6888 namespace body except that the number of empty lines between consecutive 6889 nested namespace definitions is not increased. 6890 6891 .. code-block:: c++ 6892 6893 namespace N1 { 6894 namespace N2 { 6895 6896 function(); 6897 6898 } 6899 } 6900 6901 * ``WNBWELS_Leave`` (in configuration: ``Leave``) 6902 Keep existing newlines at the beginning and the end of namespace body. 6903 ``MaxEmptyLinesToKeep`` still applies. 6904 6905 6906 6907.. END_FORMAT_STYLE_OPTIONS 6908 6909Adding additional style options 6910=============================== 6911 6912Each additional style option adds costs to the clang-format project. Some of 6913these costs affect the clang-format development itself, as we need to make 6914sure that any given combination of options work and that new features don't 6915break any of the existing options in any way. There are also costs for end users 6916as options become less discoverable and people have to think about and make a 6917decision on options they don't really care about. 6918 6919The goal of the clang-format project is more on the side of supporting a 6920limited set of styles really well as opposed to supporting every single style 6921used by a codebase somewhere in the wild. Of course, we do want to support all 6922major projects and thus have established the following bar for adding style 6923options. Each new style option must: 6924 6925 * be used in a project of significant size (have dozens of contributors) 6926 * have a publicly accessible style guide 6927 * have a person willing to contribute and maintain patches 6928 6929Examples 6930======== 6931 6932A style similar to the `Linux Kernel style 6933<https://www.kernel.org/doc/html/latest/process/coding-style.html>`_: 6934 6935.. code-block:: yaml 6936 6937 BasedOnStyle: LLVM 6938 IndentWidth: 8 6939 UseTab: Always 6940 BreakBeforeBraces: Linux 6941 AllowShortIfStatementsOnASingleLine: false 6942 IndentCaseLabels: false 6943 6944The result is (imagine that tabs are used for indentation here): 6945 6946.. code-block:: c++ 6947 6948 void test() 6949 { 6950 switch (x) { 6951 case 0: 6952 case 1: 6953 do_something(); 6954 break; 6955 case 2: 6956 do_something_else(); 6957 break; 6958 default: 6959 break; 6960 } 6961 if (condition) 6962 do_something_completely_different(); 6963 6964 if (x == y) { 6965 q(); 6966 } else if (x > y) { 6967 w(); 6968 } else { 6969 r(); 6970 } 6971 } 6972 6973A style similar to the default Visual Studio formatting style: 6974 6975.. code-block:: yaml 6976 6977 UseTab: Never 6978 IndentWidth: 4 6979 BreakBeforeBraces: Allman 6980 AllowShortIfStatementsOnASingleLine: false 6981 IndentCaseLabels: false 6982 ColumnLimit: 0 6983 6984The result is: 6985 6986.. code-block:: c++ 6987 6988 void test() 6989 { 6990 switch (suffix) 6991 { 6992 case 0: 6993 case 1: 6994 do_something(); 6995 break; 6996 case 2: 6997 do_something_else(); 6998 break; 6999 default: 7000 break; 7001 } 7002 if (condition) 7003 do_something_completely_different(); 7004 7005 if (x == y) 7006 { 7007 q(); 7008 } 7009 else if (x > y) 7010 { 7011 w(); 7012 } 7013 else 7014 { 7015 r(); 7016 } 7017 } 7018