clang/docs/ClangFormatStyleOptions.rst

   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 ==========================
  16 Clang-Format Style Options
  17 ==========================
  18
  19 :doc:`ClangFormatStyleOptions` describes configurable formatting style options
  20 supported by :doc:`LibFormat` and :doc:`ClangFormat`.
  21
  22 When using :program:`clang-format` command line utility or
  23 ``clang::format::reformat(...)`` functions from code, one can either use one of
  24 the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or
  25 create a custom style by configuring specific style options.
  26
  27
  28 Configuring Style with clang-format
  29 ===================================
  30
  31 :program:`clang-format` supports two ways to provide custom style options:
  32 directly specify style configuration in the ``-style=`` command line option or
  33 use ``-style=file`` and put style configuration in the ``.clang-format`` or
  34 ``_clang-format`` file in the project directory.
  35
  36 When using ``-style=file``, :program:`clang-format` for each input file will
  37 try to find the ``.clang-format`` file located in the closest parent directory
  38 of the input file. When the standard input is used, the search is started from
  39 the current directory.
  40
  41 When using ``-style=file:<format_file_path>``, :program:`clang-format` for
  42 each input file will use the format file located at `<format_file_path>`.
  43 The path may be absolute or relative to the working directory.
  44
  45 The ``.clang-format`` file uses YAML format:
  46
  47 .. code-block:: yaml
  48
  49   key1: value1
  50   key2: value2
  51   # A comment.
  52   ...
  53
  54 The configuration file can consist of several sections each having different
  55 ``Language:`` parameter denoting the programming language this section of the
  56 configuration is targeted at. See the description of the **Language** option
  57 below for the list of supported languages. The first section may have no
  58 language set, it will set the default style options for all languages.
  59 Configuration sections for specific language will override options set in the
  60 default section.
  61
  62 When :program:`clang-format` formats a file, it auto-detects the language using
  63 the file name. When formatting standard input or a file that doesn't have the
  64 extension corresponding to its language, ``-assume-filename=`` option can be
  65 used to override the file name :program:`clang-format` uses to detect the
  66 language.
  67
  68 An 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
  95 An easy way to get a valid ``.clang-format`` file containing all configuration
  96 options of a certain predefined style is:
  97
  98 .. code-block:: console
  99
 100   clang-format -style=llvm -dump-config > .clang-format
 101
 102 When specifying configuration in the ``-style=`` option, the same configuration
 103 is 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
 110 Disabling Formatting on a Piece of Code
 111 =======================================
 112
 113 Clang-format understands also special comments that switch formatting in a
 114 delimited 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
 117 formatted (aligned) normally. Also, a colon (``:``) and additional text may
 118 follow ``// clang-format off`` or ``// clang-format on`` to explain why
 119 clang-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
 130 Configuring Style in Code
 131 =========================
 132
 133 When using ``clang::format::reformat(...)`` functions, the format is specified
 134 by supplying the `clang::format::FormatStyle
 135 <https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
 136 structure.
 137
 138
 139 Configurable Format Style Options
 140 =================================
 141
 142 This section lists the supported style options. Value type is specified for
 143 each option. For enumeration types possible values are specified both as a C++
 144 enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
 145 the 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 .. _AlwaysBreakAfterDefinitionReturnType:
2092
2093 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlwaysBreakAfterDefinitionReturnType>`
2094   The function definition return type breaking style to use.  This
2095   option is **deprecated** and is retained for backwards compatibility.
2096
2097   Possible values:
2098
2099   * ``DRTBS_None`` (in configuration: ``None``)
2100     Break after return type automatically.
2101     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
2102
2103   * ``DRTBS_All`` (in configuration: ``All``)
2104     Always break after the return type.
2105
2106   * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
2107     Always break after the return types of top-level functions.
2108
2109
2110
2111 .. _AlwaysBreakAfterReturnType:
2112
2113 **AlwaysBreakAfterReturnType** (``deprecated``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlwaysBreakAfterReturnType>`
2114   This option is renamed to ``BreakAfterReturnType``.
2115
2116 .. _AlwaysBreakBeforeMultilineStrings:
2117
2118 **AlwaysBreakBeforeMultilineStrings** (``Boolean``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakBeforeMultilineStrings>`
2119   If ``true``, always break before multiline string literals.
2120
2121   This flag is mean to make cases where there are multiple multiline strings
2122   in a file look more consistent. Thus, it will only take effect if wrapping
2123   the string at that point leads to it being indented
2124   ``ContinuationIndentWidth`` spaces from the start of the line.
2125
2126   .. code-block:: c++
2127
2128      true:                                  false:
2129      aaaa =                         vs.     aaaa = "bbbb"
2130          "bbbb"                                    "cccc";
2131          "cccc";
2132
2133 .. _AlwaysBreakTemplateDeclarations:
2134
2135 **AlwaysBreakTemplateDeclarations** (``deprecated``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakTemplateDeclarations>`
2136   This option is renamed to ``BreakTemplateDeclarations``.
2137
2138 .. _AttributeMacros:
2139
2140 **AttributeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <AttributeMacros>`
2141   A vector of strings that should be interpreted as attributes/qualifiers
2142   instead of identifiers. This can be useful for language extensions or
2143   static analyzer annotations.
2144
2145   For example:
2146
2147   .. code-block:: c++
2148
2149     x = (char *__capability)&y;
2150     int function(void) __unused;
2151     void only_writes_to_buffer(char *__output buffer);
2152
2153   In the .clang-format configuration file, this can be configured like:
2154
2155   .. code-block:: yaml
2156
2157     AttributeMacros: [__capability, __output, __unused]
2158
2159 .. _BinPackArguments:
2160
2161 **BinPackArguments** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackArguments>`
2162   If ``false``, a function call's arguments will either be all on the
2163   same line or will have one line each.
2164
2165   .. code-block:: c++
2166
2167     true:
2168     void f() {
2169       f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
2170         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
2171     }
2172
2173     false:
2174     void f() {
2175       f(aaaaaaaaaaaaaaaaaaaa,
2176         aaaaaaaaaaaaaaaaaaaa,
2177         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
2178     }
2179
2180 .. _BinPackParameters:
2181
2182 **BinPackParameters** (``BinPackParametersStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackParameters>`
2183   The bin pack parameters style to use.
2184
2185   Possible values:
2186
2187   * ``BPPS_BinPack`` (in configuration: ``BinPack``)
2188     Bin-pack parameters.
2189
2190     .. code-block:: c++
2191
2192        void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
2193               int ccccccccccccccccccccccccccccccccccccccccccc);
2194
2195   * ``BPPS_OnePerLine`` (in configuration: ``OnePerLine``)
2196     Put all parameters on the current line if they fit.
2197     Otherwise, put each one on its own line.
2198
2199     .. code-block:: c++
2200
2201        void f(int a, int b, int c);
2202
2203        void f(int a,
2204               int b,
2205               int ccccccccccccccccccccccccccccccccccccc);
2206
2207   * ``BPPS_AlwaysOnePerLine`` (in configuration: ``AlwaysOnePerLine``)
2208     Always put each parameter on its own line.
2209
2210     .. code-block:: c++
2211
2212        void f(int a,
2213               int b,
2214               int c);
2215
2216
2217
2218 .. _BitFieldColonSpacing:
2219
2220 **BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BitFieldColonSpacing>`
2221   The BitFieldColonSpacingStyle to use for bitfields.
2222
2223   Possible values:
2224
2225   * ``BFCS_Both`` (in configuration: ``Both``)
2226     Add one space on each side of the ``:``
2227
2228     .. code-block:: c++
2229
2230       unsigned bf : 2;
2231
2232   * ``BFCS_None`` (in configuration: ``None``)
2233     Add no space around the ``:`` (except when needed for
2234     ``AlignConsecutiveBitFields``).
2235
2236     .. code-block:: c++
2237
2238       unsigned bf:2;
2239
2240   * ``BFCS_Before`` (in configuration: ``Before``)
2241     Add space before the ``:`` only
2242
2243     .. code-block:: c++
2244
2245       unsigned bf :2;
2246
2247   * ``BFCS_After`` (in configuration: ``After``)
2248     Add space after the ``:`` only (space may be added before if
2249     needed for ``AlignConsecutiveBitFields``).
2250
2251     .. code-block:: c++
2252
2253       unsigned bf: 2;
2254
2255
2256
2257 .. _BraceWrapping:
2258
2259 **BraceWrapping** (``BraceWrappingFlags``) :versionbadge:`clang-format 3.8` :ref:`¶ <BraceWrapping>`
2260   Control of individual brace wrapping cases.
2261
2262   If ``BreakBeforeBraces`` is set to ``Custom``, use this to specify how
2263   each individual brace case should be handled. Otherwise, this is ignored.
2264
2265   .. code-block:: yaml
2266
2267     # Example of usage:
2268     BreakBeforeBraces: Custom
2269     BraceWrapping:
2270       AfterEnum: true
2271       AfterStruct: false
2272       SplitEmptyFunction: false
2273
2274   Nested configuration flags:
2275
2276   Precise control over the wrapping of braces.
2277
2278   .. code-block:: c++
2279
2280     # Should be declared this way:
2281     BreakBeforeBraces: Custom
2282     BraceWrapping:
2283         AfterClass: true
2284
2285   * ``bool AfterCaseLabel`` Wrap case labels.
2286
2287     .. code-block:: c++
2288
2289       false:                                true:
2290       switch (foo) {                vs.     switch (foo) {
2291         case 1: {                             case 1:
2292           bar();                              {
2293           break;                                bar();
2294         }                                       break;
2295         default: {                            }
2296           plop();                             default:
2297         }                                     {
2298       }                                         plop();
2299                                               }
2300                                             }
2301
2302   * ``bool AfterClass`` Wrap class definitions.
2303
2304     .. code-block:: c++
2305
2306       true:
2307       class foo
2308       {};
2309
2310       false:
2311       class foo {};
2312
2313   * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
2314     Wrap control statements (``if``/``for``/``while``/``switch``/..).
2315
2316     Possible values:
2317
2318     * ``BWACS_Never`` (in configuration: ``Never``)
2319       Never wrap braces after a control statement.
2320
2321       .. code-block:: c++
2322
2323         if (foo()) {
2324         } else {
2325         }
2326         for (int i = 0; i < 10; ++i) {
2327         }
2328
2329     * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
2330       Only wrap braces after a multi-line control statement.
2331
2332       .. code-block:: c++
2333
2334         if (foo && bar &&
2335             baz)
2336         {
2337           quux();
2338         }
2339         while (foo || bar) {
2340         }
2341
2342     * ``BWACS_Always`` (in configuration: ``Always``)
2343       Always wrap braces after a control statement.
2344
2345       .. code-block:: c++
2346
2347         if (foo())
2348         {
2349         } else
2350         {}
2351         for (int i = 0; i < 10; ++i)
2352         {}
2353
2354
2355   * ``bool AfterEnum`` Wrap enum definitions.
2356
2357     .. code-block:: c++
2358
2359       true:
2360       enum X : int
2361       {
2362         B
2363       };
2364
2365       false:
2366       enum X : int { B };
2367
2368   * ``bool AfterFunction`` Wrap function definitions.
2369
2370     .. code-block:: c++
2371
2372       true:
2373       void foo()
2374       {
2375         bar();
2376         bar2();
2377       }
2378
2379       false:
2380       void foo() {
2381         bar();
2382         bar2();
2383       }
2384
2385   * ``bool AfterNamespace`` Wrap namespace definitions.
2386
2387     .. code-block:: c++
2388
2389       true:
2390       namespace
2391       {
2392       int foo();
2393       int bar();
2394       }
2395
2396       false:
2397       namespace {
2398       int foo();
2399       int bar();
2400       }
2401
2402   * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
2403
2404     .. note::
2405
2406      @autoreleasepool and @synchronized blocks are wrapped
2407      according to ``AfterControlStatement`` flag.
2408
2409   * ``bool AfterStruct`` Wrap struct definitions.
2410
2411     .. code-block:: c++
2412
2413       true:
2414       struct foo
2415       {
2416         int x;
2417       };
2418
2419       false:
2420       struct foo {
2421         int x;
2422       };
2423
2424   * ``bool AfterUnion`` Wrap union definitions.
2425
2426     .. code-block:: c++
2427
2428       true:
2429       union foo
2430       {
2431         int x;
2432       }
2433
2434       false:
2435       union foo {
2436         int x;
2437       }
2438
2439   * ``bool AfterExternBlock`` Wrap extern blocks.
2440
2441     .. code-block:: c++
2442
2443       true:
2444       extern "C"
2445       {
2446         int foo();
2447       }
2448
2449       false:
2450       extern "C" {
2451       int foo();
2452       }
2453
2454   * ``bool BeforeCatch`` Wrap before ``catch``.
2455
2456     .. code-block:: c++
2457
2458       true:
2459       try {
2460         foo();
2461       }
2462       catch () {
2463       }
2464
2465       false:
2466       try {
2467         foo();
2468       } catch () {
2469       }
2470
2471   * ``bool BeforeElse`` Wrap before ``else``.
2472
2473     .. code-block:: c++
2474
2475       true:
2476       if (foo()) {
2477       }
2478       else {
2479       }
2480
2481       false:
2482       if (foo()) {
2483       } else {
2484       }
2485
2486   * ``bool BeforeLambdaBody`` Wrap lambda block.
2487
2488     .. code-block:: c++
2489
2490       true:
2491       connect(
2492         []()
2493         {
2494           foo();
2495           bar();
2496         });
2497
2498       false:
2499       connect([]() {
2500         foo();
2501         bar();
2502       });
2503
2504   * ``bool BeforeWhile`` Wrap before ``while``.
2505
2506     .. code-block:: c++
2507
2508       true:
2509       do {
2510         foo();
2511       }
2512       while (1);
2513
2514       false:
2515       do {
2516         foo();
2517       } while (1);
2518
2519   * ``bool IndentBraces`` Indent the wrapped braces themselves.
2520
2521   * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
2522     This option is used only if the opening brace of the function has
2523     already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is
2524     set, and the function could/should not be put on a single line (as per
2525     ``AllowShortFunctionsOnASingleLine`` and constructor formatting
2526     options).
2527
2528     .. code-block:: c++
2529
2530       false:          true:
2531       int f()   vs.   int f()
2532       {}              {
2533                       }
2534
2535   * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
2536     can be put on a single line. This option is used only if the opening
2537     brace of the record has already been wrapped, i.e. the ``AfterClass``
2538     (for classes) brace wrapping mode is set.
2539
2540     .. code-block:: c++
2541
2542       false:           true:
2543       class Foo   vs.  class Foo
2544       {}               {
2545                        }
2546
2547   * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
2548     This option is used only if the opening brace of the namespace has
2549     already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is
2550     set.
2551
2552     .. code-block:: c++
2553
2554       false:               true:
2555       namespace Foo   vs.  namespace Foo
2556       {}                   {
2557                            }
2558
2559
2560 .. _BracedInitializerIndentWidth:
2561
2562 **BracedInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 17` :ref:`¶ <BracedInitializerIndentWidth>`
2563   The number of columns to use to indent the contents of braced init lists.
2564   If unset, ``ContinuationIndentWidth`` is used.
2565
2566   .. code-block:: c++
2567
2568     AlignAfterOpenBracket: AlwaysBreak
2569     BracedInitializerIndentWidth: 2
2570
2571     void f() {
2572       SomeClass c{
2573         "foo",
2574         "bar",
2575         "baz",
2576       };
2577       auto s = SomeStruct{
2578         .foo = "foo",
2579         .bar = "bar",
2580         .baz = "baz",
2581       };
2582       SomeArrayT a[3] = {
2583         {
2584           foo,
2585           bar,
2586         },
2587         {
2588           foo,
2589           bar,
2590         },
2591         SomeArrayT{},
2592       };
2593     }
2594
2595 .. _BreakAdjacentStringLiterals:
2596
2597 **BreakAdjacentStringLiterals** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <BreakAdjacentStringLiterals>`
2598   Break between adjacent string literals.
2599
2600   .. code-block:: c++
2601
2602      true:
2603      return "Code"
2604             "\0\52\26\55\55\0"
2605             "x013"
2606             "\02\xBA";
2607      false:
2608      return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA";
2609
2610 .. _BreakAfterAttributes:
2611
2612 **BreakAfterAttributes** (``AttributeBreakingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakAfterAttributes>`
2613   Break after a group of C++11 attributes before variable or function
2614   (including constructor/destructor) declaration/definition names or before
2615   control statements, i.e. ``if``, ``switch`` (including ``case`` and
2616   ``default`` labels), ``for``, and ``while`` statements.
2617
2618   Possible values:
2619
2620   * ``ABS_Always`` (in configuration: ``Always``)
2621     Always break after attributes.
2622
2623     .. code-block:: c++
2624
2625       [[maybe_unused]]
2626       const int i;
2627       [[gnu::const]] [[maybe_unused]]
2628       int j;
2629
2630       [[nodiscard]]
2631       inline int f();
2632       [[gnu::const]] [[nodiscard]]
2633       int g();
2634
2635       [[likely]]
2636       if (a)
2637         f();
2638       else
2639         g();
2640
2641       switch (b) {
2642       [[unlikely]]
2643       case 1:
2644         ++b;
2645         break;
2646       [[likely]]
2647       default:
2648         return;
2649       }
2650
2651   * ``ABS_Leave`` (in configuration: ``Leave``)
2652     Leave the line breaking after attributes as is.
2653
2654     .. code-block:: c++
2655
2656       [[maybe_unused]] const int i;
2657       [[gnu::const]] [[maybe_unused]]
2658       int j;
2659
2660       [[nodiscard]] inline int f();
2661       [[gnu::const]] [[nodiscard]]
2662       int g();
2663
2664       [[likely]] if (a)
2665         f();
2666       else
2667         g();
2668
2669       switch (b) {
2670       [[unlikely]] case 1:
2671         ++b;
2672         break;
2673       [[likely]]
2674       default:
2675         return;
2676       }
2677
2678   * ``ABS_Never`` (in configuration: ``Never``)
2679     Never break after attributes.
2680
2681     .. code-block:: c++
2682
2683       [[maybe_unused]] const int i;
2684       [[gnu::const]] [[maybe_unused]] int j;
2685
2686       [[nodiscard]] inline int f();
2687       [[gnu::const]] [[nodiscard]] int g();
2688
2689       [[likely]] if (a)
2690         f();
2691       else
2692         g();
2693
2694       switch (b) {
2695       [[unlikely]] case 1:
2696         ++b;
2697         break;
2698       [[likely]] default:
2699         return;
2700       }
2701
2702
2703
2704 .. _BreakAfterJavaFieldAnnotations:
2705
2706 **BreakAfterJavaFieldAnnotations** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <BreakAfterJavaFieldAnnotations>`
2707   Break after each annotation on a field in Java files.
2708
2709   .. code-block:: java
2710
2711      true:                                  false:
2712      @Partial                       vs.     @Partial @Mock DataLoad loader;
2713      @Mock
2714      DataLoad loader;
2715
2716 .. _BreakAfterReturnType:
2717
2718 **BreakAfterReturnType** (``ReturnTypeBreakingStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakAfterReturnType>`
2719   The function declaration return type breaking style to use.
2720
2721   Possible values:
2722
2723   * ``RTBS_None`` (in configuration: ``None``)
2724     This is **deprecated**. See ``Automatic`` below.
2725
2726   * ``RTBS_Automatic`` (in configuration: ``Automatic``)
2727     Break after return type based on ``PenaltyReturnTypeOnItsOwnLine``.
2728
2729     .. code-block:: c++
2730
2731       class A {
2732         int f() { return 0; };
2733       };
2734       int f();
2735       int f() { return 1; }
2736       int
2737       LongName::AnotherLongName();
2738
2739   * ``RTBS_ExceptShortType`` (in configuration: ``ExceptShortType``)
2740     Same as ``Automatic`` above, except that there is no break after short
2741     return types.
2742
2743     .. code-block:: c++
2744
2745       class A {
2746         int f() { return 0; };
2747       };
2748       int f();
2749       int f() { return 1; }
2750       int LongName::
2751           AnotherLongName();
2752
2753   * ``RTBS_All`` (in configuration: ``All``)
2754     Always break after the return type.
2755
2756     .. code-block:: c++
2757
2758       class A {
2759         int
2760         f() {
2761           return 0;
2762         };
2763       };
2764       int
2765       f();
2766       int
2767       f() {
2768         return 1;
2769       }
2770       int
2771       LongName::AnotherLongName();
2772
2773   * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
2774     Always break after the return types of top-level functions.
2775
2776     .. code-block:: c++
2777
2778       class A {
2779         int f() { return 0; };
2780       };
2781       int
2782       f();
2783       int
2784       f() {
2785         return 1;
2786       }
2787       int
2788       LongName::AnotherLongName();
2789
2790   * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
2791     Always break after the return type of function definitions.
2792
2793     .. code-block:: c++
2794
2795       class A {
2796         int
2797         f() {
2798           return 0;
2799         };
2800       };
2801       int f();
2802       int
2803       f() {
2804         return 1;
2805       }
2806       int
2807       LongName::AnotherLongName();
2808
2809   * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
2810     Always break after the return type of top-level definitions.
2811
2812     .. code-block:: c++
2813
2814       class A {
2815         int f() { return 0; };
2816       };
2817       int f();
2818       int
2819       f() {
2820         return 1;
2821       }
2822       int
2823       LongName::AnotherLongName();
2824
2825
2826
2827 .. _BreakArrays:
2828
2829 **BreakArrays** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <BreakArrays>`
2830   If ``true``, clang-format will always break after a Json array ``[``
2831   otherwise it will scan until the closing ``]`` to determine if it should
2832   add newlines between elements (prettier compatible).
2833
2834
2835   .. note::
2836
2837    This is currently only for formatting JSON.
2838
2839   .. code-block:: c++
2840
2841      true:                                  false:
2842      [                          vs.      [1, 2, 3, 4]
2843        1,
2844        2,
2845        3,
2846        4
2847      ]
2848
2849 .. _BreakBeforeBinaryOperators:
2850
2851 **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) :versionbadge:`clang-format 3.6` :ref:`¶ <BreakBeforeBinaryOperators>`
2852   The way to wrap binary operators.
2853
2854   Possible values:
2855
2856   * ``BOS_None`` (in configuration: ``None``)
2857     Break after operators.
2858
2859     .. code-block:: c++
2860
2861        LooooooooooongType loooooooooooooooooooooongVariable =
2862            someLooooooooooooooooongFunction();
2863
2864        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
2865                             aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
2866                         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
2867                     aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
2868                         ccccccccccccccccccccccccccccccccccccccccc;
2869
2870   * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
2871     Break before operators that aren't assignments.
2872
2873     .. code-block:: c++
2874
2875        LooooooooooongType loooooooooooooooooooooongVariable =
2876            someLooooooooooooooooongFunction();
2877
2878        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2879                             + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2880                         == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2881                     && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2882                            > ccccccccccccccccccccccccccccccccccccccccc;
2883
2884   * ``BOS_All`` (in configuration: ``All``)
2885     Break before operators.
2886
2887     .. code-block:: c++
2888
2889        LooooooooooongType loooooooooooooooooooooongVariable
2890            = someLooooooooooooooooongFunction();
2891
2892        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2893                             + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2894                         == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2895                     && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
2896                            > ccccccccccccccccccccccccccccccccccccccccc;
2897
2898
2899
2900 .. _BreakBeforeBraces:
2901
2902 **BreakBeforeBraces** (``BraceBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeBraces>`
2903   The brace breaking style to use.
2904
2905   Possible values:
2906
2907   * ``BS_Attach`` (in configuration: ``Attach``)
2908     Always attach braces to surrounding context.
2909
2910     .. code-block:: c++
2911
2912       namespace N {
2913       enum E {
2914         E1,
2915         E2,
2916       };
2917
2918       class C {
2919       public:
2920         C();
2921       };
2922
2923       bool baz(int i) {
2924         try {
2925           do {
2926             switch (i) {
2927             case 1: {
2928               foobar();
2929               break;
2930             }
2931             default: {
2932               break;
2933             }
2934             }
2935           } while (--i);
2936           return true;
2937         } catch (...) {
2938           handleError();
2939           return false;
2940         }
2941       }
2942
2943       void foo(bool b) {
2944         if (b) {
2945           baz(2);
2946         } else {
2947           baz(5);
2948         }
2949       }
2950
2951       void bar() { foo(true); }
2952       } // namespace N
2953
2954   * ``BS_Linux`` (in configuration: ``Linux``)
2955     Like ``Attach``, but break before braces on function, namespace and
2956     class definitions.
2957
2958     .. code-block:: c++
2959
2960       namespace N
2961       {
2962       enum E {
2963         E1,
2964         E2,
2965       };
2966
2967       class C
2968       {
2969       public:
2970         C();
2971       };
2972
2973       bool baz(int i)
2974       {
2975         try {
2976           do {
2977             switch (i) {
2978             case 1: {
2979               foobar();
2980               break;
2981             }
2982             default: {
2983               break;
2984             }
2985             }
2986           } while (--i);
2987           return true;
2988         } catch (...) {
2989           handleError();
2990           return false;
2991         }
2992       }
2993
2994       void foo(bool b)
2995       {
2996         if (b) {
2997           baz(2);
2998         } else {
2999           baz(5);
3000         }
3001       }
3002
3003       void bar() { foo(true); }
3004       } // namespace N
3005
3006   * ``BS_Mozilla`` (in configuration: ``Mozilla``)
3007     Like ``Attach``, but break before braces on enum, function, and record
3008     definitions.
3009
3010     .. code-block:: c++
3011
3012       namespace N {
3013       enum E
3014       {
3015         E1,
3016         E2,
3017       };
3018
3019       class C
3020       {
3021       public:
3022         C();
3023       };
3024
3025       bool baz(int i)
3026       {
3027         try {
3028           do {
3029             switch (i) {
3030             case 1: {
3031               foobar();
3032               break;
3033             }
3034             default: {
3035               break;
3036             }
3037             }
3038           } while (--i);
3039           return true;
3040         } catch (...) {
3041           handleError();
3042           return false;
3043         }
3044       }
3045
3046       void foo(bool b)
3047       {
3048         if (b) {
3049           baz(2);
3050         } else {
3051           baz(5);
3052         }
3053       }
3054
3055       void bar() { foo(true); }
3056       } // namespace N
3057
3058   * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
3059     Like ``Attach``, but break before function definitions, ``catch``, and
3060     ``else``.
3061
3062     .. code-block:: c++
3063
3064       namespace N {
3065       enum E {
3066         E1,
3067         E2,
3068       };
3069
3070       class C {
3071       public:
3072         C();
3073       };
3074
3075       bool baz(int i)
3076       {
3077         try {
3078           do {
3079             switch (i) {
3080             case 1: {
3081               foobar();
3082               break;
3083             }
3084             default: {
3085               break;
3086             }
3087             }
3088           } while (--i);
3089           return true;
3090         }
3091         catch (...) {
3092           handleError();
3093           return false;
3094         }
3095       }
3096
3097       void foo(bool b)
3098       {
3099         if (b) {
3100           baz(2);
3101         }
3102         else {
3103           baz(5);
3104         }
3105       }
3106
3107       void bar() { foo(true); }
3108       } // namespace N
3109
3110   * ``BS_Allman`` (in configuration: ``Allman``)
3111     Always break before braces.
3112
3113     .. code-block:: c++
3114
3115       namespace N
3116       {
3117       enum E
3118       {
3119         E1,
3120         E2,
3121       };
3122
3123       class C
3124       {
3125       public:
3126         C();
3127       };
3128
3129       bool baz(int i)
3130       {
3131         try
3132         {
3133           do
3134           {
3135             switch (i)
3136             {
3137             case 1:
3138             {
3139               foobar();
3140               break;
3141             }
3142             default:
3143             {
3144               break;
3145             }
3146             }
3147           } while (--i);
3148           return true;
3149         }
3150         catch (...)
3151         {
3152           handleError();
3153           return false;
3154         }
3155       }
3156
3157       void foo(bool b)
3158       {
3159         if (b)
3160         {
3161           baz(2);
3162         }
3163         else
3164         {
3165           baz(5);
3166         }
3167       }
3168
3169       void bar() { foo(true); }
3170       } // namespace N
3171
3172   * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``)
3173     Like ``Allman`` but always indent braces and line up code with braces.
3174
3175     .. code-block:: c++
3176
3177       namespace N
3178         {
3179       enum E
3180         {
3181         E1,
3182         E2,
3183         };
3184
3185       class C
3186         {
3187       public:
3188         C();
3189         };
3190
3191       bool baz(int i)
3192         {
3193         try
3194           {
3195           do
3196             {
3197             switch (i)
3198               {
3199               case 1:
3200               {
3201               foobar();
3202               break;
3203               }
3204               default:
3205               {
3206               break;
3207               }
3208               }
3209             } while (--i);
3210           return true;
3211           }
3212         catch (...)
3213           {
3214           handleError();
3215           return false;
3216           }
3217         }
3218
3219       void foo(bool b)
3220         {
3221         if (b)
3222           {
3223           baz(2);
3224           }
3225         else
3226           {
3227           baz(5);
3228           }
3229         }
3230
3231       void bar() { foo(true); }
3232         } // namespace N
3233
3234   * ``BS_GNU`` (in configuration: ``GNU``)
3235     Always break before braces and add an extra level of indentation to
3236     braces of control statements, not to those of class, function
3237     or other definitions.
3238
3239     .. code-block:: c++
3240
3241       namespace N
3242       {
3243       enum E
3244       {
3245         E1,
3246         E2,
3247       };
3248
3249       class C
3250       {
3251       public:
3252         C();
3253       };
3254
3255       bool baz(int i)
3256       {
3257         try
3258           {
3259             do
3260               {
3261                 switch (i)
3262                   {
3263                   case 1:
3264                     {
3265                       foobar();
3266                       break;
3267                     }
3268                   default:
3269                     {
3270                       break;
3271                     }
3272                   }
3273               }
3274             while (--i);
3275             return true;
3276           }
3277         catch (...)
3278           {
3279             handleError();
3280             return false;
3281           }
3282       }
3283
3284       void foo(bool b)
3285       {
3286         if (b)
3287           {
3288             baz(2);
3289           }
3290         else
3291           {
3292             baz(5);
3293           }
3294       }
3295
3296       void bar() { foo(true); }
3297       } // namespace N
3298
3299   * ``BS_WebKit`` (in configuration: ``WebKit``)
3300     Like ``Attach``, but break before functions.
3301
3302     .. code-block:: c++
3303
3304       namespace N {
3305       enum E {
3306         E1,
3307         E2,
3308       };
3309
3310       class C {
3311       public:
3312         C();
3313       };
3314
3315       bool baz(int i)
3316       {
3317         try {
3318           do {
3319             switch (i) {
3320             case 1: {
3321               foobar();
3322               break;
3323             }
3324             default: {
3325               break;
3326             }
3327             }
3328           } while (--i);
3329           return true;
3330         } catch (...) {
3331           handleError();
3332           return false;
3333         }
3334       }
3335
3336       void foo(bool b)
3337       {
3338         if (b) {
3339           baz(2);
3340         } else {
3341           baz(5);
3342         }
3343       }
3344
3345       void bar() { foo(true); }
3346       } // namespace N
3347
3348   * ``BS_Custom`` (in configuration: ``Custom``)
3349     Configure each individual brace in ``BraceWrapping``.
3350
3351
3352
3353 .. _BreakBeforeConceptDeclarations:
3354
3355 **BreakBeforeConceptDeclarations** (``BreakBeforeConceptDeclarationsStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BreakBeforeConceptDeclarations>`
3356   The concept declaration style to use.
3357
3358   Possible values:
3359
3360   * ``BBCDS_Never`` (in configuration: ``Never``)
3361     Keep the template declaration line together with ``concept``.
3362
3363     .. code-block:: c++
3364
3365       template <typename T> concept C = ...;
3366
3367   * ``BBCDS_Allowed`` (in configuration: ``Allowed``)
3368     Breaking between template declaration and ``concept`` is allowed. The
3369     actual behavior depends on the content and line breaking rules and
3370     penalties.
3371
3372   * ``BBCDS_Always`` (in configuration: ``Always``)
3373     Always break before ``concept``, putting it in the line after the
3374     template declaration.
3375
3376     .. code-block:: c++
3377
3378       template <typename T>
3379       concept C = ...;
3380
3381
3382
3383 .. _BreakBeforeInlineASMColon:
3384
3385 **BreakBeforeInlineASMColon** (``BreakBeforeInlineASMColonStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakBeforeInlineASMColon>`
3386   The inline ASM colon style to use.
3387
3388   Possible values:
3389
3390   * ``BBIAS_Never`` (in configuration: ``Never``)
3391     No break before inline ASM colon.
3392
3393     .. code-block:: c++
3394
3395        asm volatile("string", : : val);
3396
3397   * ``BBIAS_OnlyMultiline`` (in configuration: ``OnlyMultiline``)
3398     Break before inline ASM colon if the line length is longer than column
3399     limit.
3400
3401     .. code-block:: c++
3402
3403        asm volatile("string", : : val);
3404        asm("cmoveq %1, %2, %[result]"
3405            : [result] "=r"(result)
3406            : "r"(test), "r"(new), "[result]"(old));
3407
3408   * ``BBIAS_Always`` (in configuration: ``Always``)
3409     Always break before inline ASM colon.
3410
3411     .. code-block:: c++
3412
3413        asm volatile("string",
3414                     :
3415                     : val);
3416
3417
3418
3419 .. _BreakBeforeTernaryOperators:
3420
3421 **BreakBeforeTernaryOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeTernaryOperators>`
3422   If ``true``, ternary operators will be placed after line breaks.
3423
3424   .. code-block:: c++
3425
3426      true:
3427      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
3428          ? firstValue
3429          : SecondValueVeryVeryVeryVeryLong;
3430
3431      false:
3432      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
3433          firstValue :
3434          SecondValueVeryVeryVeryVeryLong;
3435
3436 .. _BreakBinaryOperations:
3437
3438 **BreakBinaryOperations** (``BreakBinaryOperationsStyle``) :versionbadge:`clang-format 20` :ref:`¶ <BreakBinaryOperations>`
3439   The break constructor initializers style to use.
3440
3441   Possible values:
3442
3443   * ``BBO_Never`` (in configuration: ``Never``)
3444     Don't break binary operations
3445
3446     .. code-block:: c++
3447
3448        aaa + bbbb * ccccc - ddddd +
3449        eeeeeeeeeeeeeeee;
3450
3451   * ``BBO_OnePerLine`` (in configuration: ``OnePerLine``)
3452     Binary operations will either be all on the same line, or each operation
3453     will have one line each.
3454
3455     .. code-block:: c++
3456
3457        aaa +
3458        bbbb *
3459        ccccc -
3460        ddddd +
3461        eeeeeeeeeeeeeeee;
3462
3463   * ``BBO_RespectPrecedence`` (in configuration: ``RespectPrecedence``)
3464     Binary operations of a particular precedence that exceed the column
3465     limit will have one line each.
3466
3467     .. code-block:: c++
3468
3469        aaa +
3470        bbbb * ccccc -
3471        ddddd +
3472        eeeeeeeeeeeeeeee;
3473
3474
3475
3476 .. _BreakConstructorInitializers:
3477
3478 **BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) :versionbadge:`clang-format 5` :ref:`¶ <BreakConstructorInitializers>`
3479   The break constructor initializers style to use.
3480
3481   Possible values:
3482
3483   * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
3484     Break constructor initializers before the colon and after the commas.
3485
3486     .. code-block:: c++
3487
3488        Constructor()
3489            : initializer1(),
3490              initializer2()
3491
3492   * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
3493     Break constructor initializers before the colon and commas, and align
3494     the commas with the colon.
3495
3496     .. code-block:: c++
3497
3498        Constructor()
3499            : initializer1()
3500            , initializer2()
3501
3502   * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
3503     Break constructor initializers after the colon and commas.
3504
3505     .. code-block:: c++
3506
3507        Constructor() :
3508            initializer1(),
3509            initializer2()
3510
3511
3512
3513 .. _BreakFunctionDefinitionParameters:
3514
3515 **BreakFunctionDefinitionParameters** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <BreakFunctionDefinitionParameters>`
3516   If ``true``, clang-format will always break before function definition
3517   parameters.
3518
3519   .. code-block:: c++
3520
3521      true:
3522      void functionDefinition(
3523               int A, int B) {}
3524
3525      false:
3526      void functionDefinition(int A, int B) {}
3527
3528 .. _BreakInheritanceList:
3529
3530 **BreakInheritanceList** (``BreakInheritanceListStyle``) :versionbadge:`clang-format 7` :ref:`¶ <BreakInheritanceList>`
3531   The inheritance list style to use.
3532
3533   Possible values:
3534
3535   * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
3536     Break inheritance list before the colon and after the commas.
3537
3538     .. code-block:: c++
3539
3540        class Foo
3541            : Base1,
3542              Base2
3543        {};
3544
3545   * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
3546     Break inheritance list before the colon and commas, and align
3547     the commas with the colon.
3548
3549     .. code-block:: c++
3550
3551        class Foo
3552            : Base1
3553            , Base2
3554        {};
3555
3556   * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
3557     Break inheritance list after the colon and commas.
3558
3559     .. code-block:: c++
3560
3561        class Foo :
3562            Base1,
3563            Base2
3564        {};
3565
3566   * ``BILS_AfterComma`` (in configuration: ``AfterComma``)
3567     Break inheritance list only after the commas.
3568
3569     .. code-block:: c++
3570
3571        class Foo : Base1,
3572                    Base2
3573        {};
3574
3575
3576
3577 .. _BreakStringLiterals:
3578
3579 **BreakStringLiterals** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <BreakStringLiterals>`
3580   Allow breaking string literals when formatting.
3581
3582   In C, C++, and Objective-C:
3583
3584   .. code-block:: c++
3585
3586      true:
3587      const char* x = "veryVeryVeryVeryVeryVe"
3588                      "ryVeryVeryVeryVeryVery"
3589                      "VeryLongString";
3590
3591      false:
3592      const char* x =
3593          "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
3594
3595   In C# and Java:
3596
3597   .. code-block:: c++
3598
3599      true:
3600      string x = "veryVeryVeryVeryVeryVe" +
3601                 "ryVeryVeryVeryVeryVery" +
3602                 "VeryLongString";
3603
3604      false:
3605      string x =
3606          "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
3607
3608   C# interpolated strings are not broken.
3609
3610   In Verilog:
3611
3612   .. code-block:: c++
3613
3614      true:
3615      string x = {"veryVeryVeryVeryVeryVe",
3616                  "ryVeryVeryVeryVeryVery",
3617                  "VeryLongString"};
3618
3619      false:
3620      string x =
3621          "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
3622
3623 .. _BreakTemplateDeclarations:
3624
3625 **BreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakTemplateDeclarations>`
3626   The template declaration breaking style to use.
3627
3628   Possible values:
3629
3630   * ``BTDS_Leave`` (in configuration: ``Leave``)
3631     Do not change the line breaking before the declaration.
3632
3633     .. code-block:: c++
3634
3635        template <typename T>
3636        T foo() {
3637        }
3638        template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
3639                                    int bbbbbbbbbbbbbbbbbbbbb) {
3640        }
3641
3642   * ``BTDS_No`` (in configuration: ``No``)
3643     Do not force break before declaration.
3644     ``PenaltyBreakTemplateDeclaration`` is taken into account.
3645
3646     .. code-block:: c++
3647
3648        template <typename T> T foo() {
3649        }
3650        template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
3651                                    int bbbbbbbbbbbbbbbbbbbbb) {
3652        }
3653
3654   * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
3655     Force break after template declaration only when the following
3656     declaration spans multiple lines.
3657
3658     .. code-block:: c++
3659
3660        template <typename T> T foo() {
3661        }
3662        template <typename T>
3663        T foo(int aaaaaaaaaaaaaaaaaaaaa,
3664              int bbbbbbbbbbbbbbbbbbbbb) {
3665        }
3666
3667   * ``BTDS_Yes`` (in configuration: ``Yes``)
3668     Always break after template declaration.
3669
3670     .. code-block:: c++
3671
3672        template <typename T>
3673        T foo() {
3674        }
3675        template <typename T>
3676        T foo(int aaaaaaaaaaaaaaaaaaaaa,
3677              int bbbbbbbbbbbbbbbbbbbbb) {
3678        }
3679
3680
3681
3682 .. _ColumnLimit:
3683
3684 **ColumnLimit** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ColumnLimit>`
3685   The column limit.
3686
3687   A column limit of ``0`` means that there is no column limit. In this case,
3688   clang-format will respect the input's line breaking decisions within
3689   statements unless they contradict other rules.
3690
3691 .. _CommentPragmas:
3692
3693 **CommentPragmas** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <CommentPragmas>`
3694   A regular expression that describes comments with special meaning,
3695   which should not be split into lines or otherwise changed.
3696
3697   .. code-block:: c++
3698
3699      // CommentPragmas: '^ FOOBAR pragma:'
3700      // Will leave the following line unaffected
3701      #include <vector> // FOOBAR pragma: keep
3702
3703 .. _CompactNamespaces:
3704
3705 **CompactNamespaces** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <CompactNamespaces>`
3706   If ``true``, consecutive namespace declarations will be on the same
3707   line. If ``false``, each namespace is declared on a new line.
3708
3709   .. code-block:: c++
3710
3711     true:
3712     namespace Foo { namespace Bar {
3713     }}
3714
3715     false:
3716     namespace Foo {
3717     namespace Bar {
3718     }
3719     }
3720
3721   If it does not fit on a single line, the overflowing namespaces get
3722   wrapped:
3723
3724   .. code-block:: c++
3725
3726     namespace Foo { namespace Bar {
3727     namespace Extra {
3728     }}}
3729
3730 .. _ConstructorInitializerAllOnOneLineOrOnePerLine:
3731
3732 **ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerAllOnOneLineOrOnePerLine>`
3733   This option is **deprecated**. See ``CurrentLine`` of
3734   ``PackConstructorInitializers``.
3735
3736 .. _ConstructorInitializerIndentWidth:
3737
3738 **ConstructorInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerIndentWidth>`
3739   The number of characters to use for indentation of constructor
3740   initializer lists as well as inheritance lists.
3741
3742 .. _ContinuationIndentWidth:
3743
3744 **ContinuationIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ContinuationIndentWidth>`
3745   Indent width for line continuations.
3746
3747   .. code-block:: c++
3748
3749      ContinuationIndentWidth: 2
3750
3751      int i =         //  VeryVeryVeryVeryVeryLongComment
3752        longFunction( // Again a long comment
3753          arg);
3754
3755 .. _Cpp11BracedListStyle:
3756
3757 **Cpp11BracedListStyle** (``Boolean``) :versionbadge:`clang-format 3.4` :ref:`¶ <Cpp11BracedListStyle>`
3758   If ``true``, format braced lists as best suited for C++11 braced
3759   lists.
3760
3761   Important differences:
3762   - No spaces inside the braced list.
3763   - No line break before the closing brace.
3764   - Indentation with the continuation indent, not with the block indent.
3765
3766   Fundamentally, C++11 braced lists are formatted exactly like function
3767   calls would be formatted in their place. If the braced list follows a name
3768   (e.g. a type or variable name), clang-format formats as if the ``{}`` were
3769   the parentheses of a function call with that name. If there is no name,
3770   a zero-length name is assumed.
3771
3772   .. code-block:: c++
3773
3774      true:                                  false:
3775      vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
3776      vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
3777      f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
3778      new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
3779
3780 .. _DeriveLineEnding:
3781
3782 **DeriveLineEnding** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <DeriveLineEnding>`
3783   This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of
3784   ``LineEnding``.
3785
3786 .. _DerivePointerAlignment:
3787
3788 **DerivePointerAlignment** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DerivePointerAlignment>`
3789   If ``true``, analyze the formatted file for the most common
3790   alignment of ``&`` and ``*``.
3791   Pointer and reference alignment styles are going to be updated according
3792   to the preferences found in the file.
3793   ``PointerAlignment`` is then used only as fallback.
3794
3795 .. _DisableFormat:
3796
3797 **DisableFormat** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DisableFormat>`
3798   Disables formatting completely.
3799
3800 .. _EmptyLineAfterAccessModifier:
3801
3802 **EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) :versionbadge:`clang-format 13` :ref:`¶ <EmptyLineAfterAccessModifier>`
3803   Defines when to put an empty line after access modifiers.
3804   ``EmptyLineBeforeAccessModifier`` configuration handles the number of
3805   empty lines between two access modifiers.
3806
3807   Possible values:
3808
3809   * ``ELAAMS_Never`` (in configuration: ``Never``)
3810     Remove all empty lines after access modifiers.
3811
3812     .. code-block:: c++
3813
3814       struct foo {
3815       private:
3816         int i;
3817       protected:
3818         int j;
3819         /* comment */
3820       public:
3821         foo() {}
3822       private:
3823       protected:
3824       };
3825
3826   * ``ELAAMS_Leave`` (in configuration: ``Leave``)
3827     Keep existing empty lines after access modifiers.
3828     MaxEmptyLinesToKeep is applied instead.
3829
3830   * ``ELAAMS_Always`` (in configuration: ``Always``)
3831     Always add empty line after access modifiers if there are none.
3832     MaxEmptyLinesToKeep is applied also.
3833
3834     .. code-block:: c++
3835
3836       struct foo {
3837       private:
3838
3839         int i;
3840       protected:
3841
3842         int j;
3843         /* comment */
3844       public:
3845
3846         foo() {}
3847       private:
3848
3849       protected:
3850
3851       };
3852
3853
3854
3855 .. _EmptyLineBeforeAccessModifier:
3856
3857 **EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) :versionbadge:`clang-format 12` :ref:`¶ <EmptyLineBeforeAccessModifier>`
3858   Defines in which cases to put empty line before access modifiers.
3859
3860   Possible values:
3861
3862   * ``ELBAMS_Never`` (in configuration: ``Never``)
3863     Remove all empty lines before access modifiers.
3864
3865     .. code-block:: c++
3866
3867       struct foo {
3868       private:
3869         int i;
3870       protected:
3871         int j;
3872         /* comment */
3873       public:
3874         foo() {}
3875       private:
3876       protected:
3877       };
3878
3879   * ``ELBAMS_Leave`` (in configuration: ``Leave``)
3880     Keep existing empty lines before access modifiers.
3881
3882   * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``)
3883     Add empty line only when access modifier starts a new logical block.
3884     Logical block is a group of one or more member fields or functions.
3885
3886     .. code-block:: c++
3887
3888       struct foo {
3889       private:
3890         int i;
3891
3892       protected:
3893         int j;
3894         /* comment */
3895       public:
3896         foo() {}
3897
3898       private:
3899       protected:
3900       };
3901
3902   * ``ELBAMS_Always`` (in configuration: ``Always``)
3903     Always add empty line before access modifiers unless access modifier
3904     is at the start of struct or class definition.
3905
3906     .. code-block:: c++
3907
3908       struct foo {
3909       private:
3910         int i;
3911
3912       protected:
3913         int j;
3914         /* comment */
3915
3916       public:
3917         foo() {}
3918
3919       private:
3920
3921       protected:
3922       };
3923
3924
3925
3926 .. _ExperimentalAutoDetectBinPacking:
3927
3928 **ExperimentalAutoDetectBinPacking** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ExperimentalAutoDetectBinPacking>`
3929   If ``true``, clang-format detects whether function calls and
3930   definitions are formatted with one parameter per line.
3931
3932   Each call can be bin-packed, one-per-line or inconclusive. If it is
3933   inconclusive, e.g. completely on one line, but a decision needs to be
3934   made, clang-format analyzes whether there are other bin-packed cases in
3935   the input file and act accordingly.
3936
3937
3938   .. note::
3939
3940    This is an experimental flag, that might go away or be renamed. Do
3941    not use this in config files, etc. Use at your own risk.
3942
3943 .. _FixNamespaceComments:
3944
3945 **FixNamespaceComments** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <FixNamespaceComments>`
3946   If ``true``, clang-format adds missing namespace end comments for
3947   namespaces and fixes invalid existing ones. This doesn't affect short
3948   namespaces, which are controlled by ``ShortNamespaceLines``.
3949
3950   .. code-block:: c++
3951
3952      true:                                  false:
3953      namespace longNamespace {      vs.     namespace longNamespace {
3954      void foo();                            void foo();
3955      void bar();                            void bar();
3956      } // namespace a                       }
3957      namespace shortNamespace {             namespace shortNamespace {
3958      void baz();                            void baz();
3959      }                                      }
3960
3961 .. _ForEachMacros:
3962
3963 **ForEachMacros** (``List of Strings``) :versionbadge:`clang-format 3.7` :ref:`¶ <ForEachMacros>`
3964   A vector of macros that should be interpreted as foreach loops
3965   instead of as function calls.
3966
3967   These are expected to be macros of the form:
3968
3969   .. code-block:: c++
3970
3971     FOREACH(<variable-declaration>, ...)
3972       <loop-body>
3973
3974   In the .clang-format configuration file, this can be configured like:
3975
3976   .. code-block:: yaml
3977
3978     ForEachMacros: [RANGES_FOR, FOREACH]
3979
3980   For example: BOOST_FOREACH.
3981
3982 .. _IfMacros:
3983
3984 **IfMacros** (``List of Strings``) :versionbadge:`clang-format 13` :ref:`¶ <IfMacros>`
3985   A vector of macros that should be interpreted as conditionals
3986   instead of as function calls.
3987
3988   These are expected to be macros of the form:
3989
3990   .. code-block:: c++
3991
3992     IF(...)
3993       <conditional-body>
3994     else IF(...)
3995       <conditional-body>
3996
3997   In the .clang-format configuration file, this can be configured like:
3998
3999   .. code-block:: yaml
4000
4001     IfMacros: [IF]
4002
4003   For example: `KJ_IF_MAYBE
4004   <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
4005
4006 .. _IncludeBlocks:
4007
4008 **IncludeBlocks** (``IncludeBlocksStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IncludeBlocks>`
4009   Dependent on the value, multiple ``#include`` blocks can be sorted
4010   as one and divided based on category.
4011
4012   Possible values:
4013
4014   * ``IBS_Preserve`` (in configuration: ``Preserve``)
4015     Sort each ``#include`` block separately.
4016
4017     .. code-block:: c++
4018
4019        #include "b.h"               into      #include "b.h"
4020
4021        #include <lib/main.h>                  #include "a.h"
4022        #include "a.h"                         #include <lib/main.h>
4023
4024   * ``IBS_Merge`` (in configuration: ``Merge``)
4025     Merge multiple ``#include`` blocks together and sort as one.
4026
4027     .. code-block:: c++
4028
4029        #include "b.h"               into      #include "a.h"
4030                                               #include "b.h"
4031        #include <lib/main.h>                  #include <lib/main.h>
4032        #include "a.h"
4033
4034   * ``IBS_Regroup`` (in configuration: ``Regroup``)
4035     Merge multiple ``#include`` blocks together and sort as one.
4036     Then split into groups based on category priority. See
4037     ``IncludeCategories``.
4038
4039     .. code-block:: c++
4040
4041        #include "b.h"               into      #include "a.h"
4042                                               #include "b.h"
4043        #include <lib/main.h>
4044        #include "a.h"                         #include <lib/main.h>
4045
4046
4047
4048 .. _IncludeCategories:
4049
4050 **IncludeCategories** (``List of IncludeCategories``) :versionbadge:`clang-format 3.8` :ref:`¶ <IncludeCategories>`
4051   Regular expressions denoting the different ``#include`` categories
4052   used for ordering ``#includes``.
4053
4054   `POSIX extended
4055   <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
4056   regular expressions are supported.
4057
4058   These regular expressions are matched against the filename of an include
4059   (including the <> or "") in order. The value belonging to the first
4060   matching regular expression is assigned and ``#includes`` are sorted first
4061   according to increasing category number and then alphabetically within
4062   each category.
4063
4064   If none of the regular expressions match, INT_MAX is assigned as
4065   category. The main header for a source file automatically gets category 0.
4066   so that it is generally kept at the beginning of the ``#includes``
4067   (https://llvm.org/docs/CodingStandards.html#include-style). However, you
4068   can also assign negative priorities if you have certain headers that
4069   always need to be first.
4070
4071   There is a third and optional field ``SortPriority`` which can used while
4072   ``IncludeBlocks = IBS_Regroup`` to define the priority in which
4073   ``#includes`` should be ordered. The value of ``Priority`` defines the
4074   order of ``#include blocks`` and also allows the grouping of ``#includes``
4075   of different priority. ``SortPriority`` is set to the value of
4076   ``Priority`` as default if it is not assigned.
4077
4078   Each regular expression can be marked as case sensitive with the field
4079   ``CaseSensitive``, per default it is not.
4080
4081   To configure this in the .clang-format file, use:
4082
4083   .. code-block:: yaml
4084
4085     IncludeCategories:
4086       - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
4087         Priority:        2
4088         SortPriority:    2
4089         CaseSensitive:   true
4090       - Regex:           '^((<|")(gtest|gmock|isl|json)/)'
4091         Priority:        3
4092       - Regex:           '<[[:alnum:].]+>'
4093         Priority:        4
4094       - Regex:           '.*'
4095         Priority:        1
4096         SortPriority:    0
4097
4098 .. _IncludeIsMainRegex:
4099
4100 **IncludeIsMainRegex** (``String``) :versionbadge:`clang-format 3.9` :ref:`¶ <IncludeIsMainRegex>`
4101   Specify a regular expression of suffixes that are allowed in the
4102   file-to-main-include mapping.
4103
4104   When guessing whether a #include is the "main" include (to assign
4105   category 0, see above), use this regex of allowed suffixes to the header
4106   stem. A partial match is done, so that:
4107   - "" means "arbitrary suffix"
4108   - "$" means "no suffix"
4109
4110   For example, if configured to "(_test)?$", then a header a.h would be seen
4111   as the "main" include in both a.cc and a_test.cc.
4112
4113 .. _IncludeIsMainSourceRegex:
4114
4115 **IncludeIsMainSourceRegex** (``String``) :versionbadge:`clang-format 10` :ref:`¶ <IncludeIsMainSourceRegex>`
4116   Specify a regular expression for files being formatted
4117   that are allowed to be considered "main" in the
4118   file-to-main-include mapping.
4119
4120   By default, clang-format considers files as "main" only when they end
4121   with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm``
4122   extensions.
4123   For these files a guessing of "main" include takes place
4124   (to assign category 0, see above). This config option allows for
4125   additional suffixes and extensions for files to be considered as "main".
4126
4127   For example, if this option is configured to ``(Impl\.hpp)$``,
4128   then a file ``ClassImpl.hpp`` is considered "main" (in addition to
4129   ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
4130   include file" logic will be executed (with *IncludeIsMainRegex* setting
4131   also being respected in later phase). Without this option set,
4132   ``ClassImpl.hpp`` would not have the main include file put on top
4133   before any other include.
4134
4135 .. _IndentAccessModifiers:
4136
4137 **IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13` :ref:`¶ <IndentAccessModifiers>`
4138   Specify whether access modifiers should have their own indentation level.
4139
4140   When ``false``, access modifiers are indented (or outdented) relative to
4141   the record members, respecting the ``AccessModifierOffset``. Record
4142   members are indented one level below the record.
4143   When ``true``, access modifiers get their own indentation level. As a
4144   consequence, record members are always indented 2 levels below the record,
4145   regardless of the access modifier presence. Value of the
4146   ``AccessModifierOffset`` is ignored.
4147
4148   .. code-block:: c++
4149
4150      false:                                 true:
4151      class C {                      vs.     class C {
4152        class D {                                class D {
4153          void bar();                                void bar();
4154        protected:                                 protected:
4155          D();                                       D();
4156        };                                       };
4157      public:                                  public:
4158        C();                                     C();
4159      };                                     };
4160      void foo() {                           void foo() {
4161        return 1;                              return 1;
4162      }                                      }
4163
4164 .. _IndentCaseBlocks:
4165
4166 **IndentCaseBlocks** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <IndentCaseBlocks>`
4167   Indent case label blocks one level from the case label.
4168
4169   When ``false``, the block following the case label uses the same
4170   indentation level as for the case label, treating the case label the same
4171   as an if-statement.
4172   When ``true``, the block gets indented as a scope block.
4173
4174   .. code-block:: c++
4175
4176      false:                                 true:
4177      switch (fool) {                vs.     switch (fool) {
4178      case 1: {                              case 1:
4179        bar();                                 {
4180      } break;                                   bar();
4181      default: {                               }
4182        plop();                                break;
4183      }                                      default:
4184      }                                        {
4185                                                 plop();
4186                                               }
4187                                             }
4188
4189 .. _IndentCaseLabels:
4190
4191 **IndentCaseLabels** (``Boolean``) :versionbadge:`clang-format 3.3` :ref:`¶ <IndentCaseLabels>`
4192   Indent case labels one level from the switch statement.
4193
4194   When ``false``, use the same indentation level as for the switch
4195   statement. Switch statement body is always indented one level more than
4196   case labels (except the first block following the case label, which
4197   itself indents the code - unless IndentCaseBlocks is enabled).
4198
4199   .. code-block:: c++
4200
4201      false:                                 true:
4202      switch (fool) {                vs.     switch (fool) {
4203      case 1:                                  case 1:
4204        bar();                                   bar();
4205        break;                                   break;
4206      default:                                 default:
4207        plop();                                  plop();
4208      }                                      }
4209
4210 .. _IndentExternBlock:
4211
4212 **IndentExternBlock** (``IndentExternBlockStyle``) :versionbadge:`clang-format 11` :ref:`¶ <IndentExternBlock>`
4213   IndentExternBlockStyle is the type of indenting of extern blocks.
4214
4215   Possible values:
4216
4217   * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``)
4218     Backwards compatible with AfterExternBlock's indenting.
4219
4220     .. code-block:: c++
4221
4222        IndentExternBlock: AfterExternBlock
4223        BraceWrapping.AfterExternBlock: true
4224        extern "C"
4225        {
4226            void foo();
4227        }
4228
4229
4230     .. code-block:: c++
4231
4232        IndentExternBlock: AfterExternBlock
4233        BraceWrapping.AfterExternBlock: false
4234        extern "C" {
4235        void foo();
4236        }
4237
4238   * ``IEBS_NoIndent`` (in configuration: ``NoIndent``)
4239     Does not indent extern blocks.
4240
4241     .. code-block:: c++
4242
4243         extern "C" {
4244         void foo();
4245         }
4246
4247   * ``IEBS_Indent`` (in configuration: ``Indent``)
4248     Indents extern blocks.
4249
4250     .. code-block:: c++
4251
4252         extern "C" {
4253           void foo();
4254         }
4255
4256
4257
4258 .. _IndentGotoLabels:
4259
4260 **IndentGotoLabels** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <IndentGotoLabels>`
4261   Indent goto labels.
4262
4263   When ``false``, goto labels are flushed left.
4264
4265   .. code-block:: c++
4266
4267      true:                                  false:
4268      int f() {                      vs.     int f() {
4269        if (foo()) {                           if (foo()) {
4270        label1:                              label1:
4271          bar();                                 bar();
4272        }                                      }
4273      label2:                                label2:
4274        return 1;                              return 1;
4275      }                                      }
4276
4277 .. _IndentPPDirectives:
4278
4279 **IndentPPDirectives** (``PPDirectiveIndentStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IndentPPDirectives>`
4280   The preprocessor directive indenting style to use.
4281
4282   Possible values:
4283
4284   * ``PPDIS_None`` (in configuration: ``None``)
4285     Does not indent any directives.
4286
4287     .. code-block:: c++
4288
4289        #if FOO
4290        #if BAR
4291        #include <foo>
4292        #endif
4293        #endif
4294
4295   * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
4296     Indents directives after the hash.
4297
4298     .. code-block:: c++
4299
4300        #if FOO
4301        #  if BAR
4302        #    include <foo>
4303        #  endif
4304        #endif
4305
4306   * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
4307     Indents directives before the hash.
4308
4309     .. code-block:: c++
4310
4311        #if FOO
4312          #if BAR
4313            #include <foo>
4314          #endif
4315        #endif
4316
4317
4318
4319 .. _IndentRequiresClause:
4320
4321 **IndentRequiresClause** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <IndentRequiresClause>`
4322   Indent the requires clause in a template. This only applies when
4323   ``RequiresClausePosition`` is ``OwnLine``, ``OwnLineWithBrace``,
4324   or ``WithFollowing``.
4325
4326   In clang-format 12, 13 and 14 it was named ``IndentRequires``.
4327
4328   .. code-block:: c++
4329
4330      true:
4331      template <typename It>
4332        requires Iterator<It>
4333      void sort(It begin, It end) {
4334        //....
4335      }
4336
4337      false:
4338      template <typename It>
4339      requires Iterator<It>
4340      void sort(It begin, It end) {
4341        //....
4342      }
4343
4344 .. _IndentWidth:
4345
4346 **IndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWidth>`
4347   The number of columns to use for indentation.
4348
4349   .. code-block:: c++
4350
4351      IndentWidth: 3
4352
4353      void f() {
4354         someFunction();
4355         if (true, false) {
4356            f();
4357         }
4358      }
4359
4360 .. _IndentWrappedFunctionNames:
4361
4362 **IndentWrappedFunctionNames** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWrappedFunctionNames>`
4363   Indent if a function definition or declaration is wrapped after the
4364   type.
4365
4366   .. code-block:: c++
4367
4368      true:
4369      LoooooooooooooooooooooooooooooooooooooooongReturnType
4370          LoooooooooooooooooooooooooooooooongFunctionDeclaration();
4371
4372      false:
4373      LoooooooooooooooooooooooooooooooooooooooongReturnType
4374      LoooooooooooooooooooooooooooooooongFunctionDeclaration();
4375
4376 .. _InsertBraces:
4377
4378 **InsertBraces** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <InsertBraces>`
4379   Insert braces after control statements (``if``, ``else``, ``for``, ``do``,
4380   and ``while``) in C++ unless the control statements are inside macro
4381   definitions or the braces would enclose preprocessor directives.
4382
4383   .. warning::
4384
4385    Setting this option to ``true`` could lead to incorrect code formatting
4386    due to clang-format's lack of complete semantic information. As such,
4387    extra care should be taken to review code changes made by this option.
4388
4389   .. code-block:: c++
4390
4391     false:                                    true:
4392
4393     if (isa<FunctionDecl>(D))        vs.      if (isa<FunctionDecl>(D)) {
4394       handleFunctionDecl(D);                    handleFunctionDecl(D);
4395     else if (isa<VarDecl>(D))                 } else if (isa<VarDecl>(D)) {
4396       handleVarDecl(D);                         handleVarDecl(D);
4397     else                                      } else {
4398       return;                                   return;
4399                                               }
4400
4401     while (i--)                      vs.      while (i--) {
4402       for (auto *A : D.attrs())                 for (auto *A : D.attrs()) {
4403         handleAttr(A);                            handleAttr(A);
4404                                                 }
4405                                               }
4406
4407     do                               vs.      do {
4408       --i;                                      --i;
4409     while (i);                                } while (i);
4410
4411 .. _InsertNewlineAtEOF:
4412
4413 **InsertNewlineAtEOF** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <InsertNewlineAtEOF>`
4414   Insert a newline at end of file if missing.
4415
4416 .. _InsertTrailingCommas:
4417
4418 **InsertTrailingCommas** (``TrailingCommaStyle``) :versionbadge:`clang-format 11` :ref:`¶ <InsertTrailingCommas>`
4419   If set to ``TCS_Wrapped`` will insert trailing commas in container
4420   literals (arrays and objects) that wrap across multiple lines.
4421   It is currently only available for JavaScript
4422   and disabled by default ``TCS_None``.
4423   ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
4424   as inserting the comma disables bin-packing.
4425
4426   .. code-block:: c++
4427
4428     TSC_Wrapped:
4429     const someArray = [
4430     aaaaaaaaaaaaaaaaaaaaaaaaaa,
4431     aaaaaaaaaaaaaaaaaaaaaaaaaa,
4432     aaaaaaaaaaaaaaaaaaaaaaaaaa,
4433     //                        ^ inserted
4434     ]
4435
4436   Possible values:
4437
4438   * ``TCS_None`` (in configuration: ``None``)
4439     Do not insert trailing commas.
4440
4441   * ``TCS_Wrapped`` (in configuration: ``Wrapped``)
4442     Insert trailing commas in container literals that were wrapped over
4443     multiple lines. Note that this is conceptually incompatible with
4444     bin-packing, because the trailing comma is used as an indicator
4445     that a container should be formatted one-per-line (i.e. not bin-packed).
4446     So inserting a trailing comma counteracts bin-packing.
4447
4448
4449
4450 .. _IntegerLiteralSeparator:
4451
4452 **IntegerLiteralSeparator** (``IntegerLiteralSeparatorStyle``) :versionbadge:`clang-format 16` :ref:`¶ <IntegerLiteralSeparator>`
4453   Format integer literal separators (``'`` for C++ and ``_`` for C#, Java,
4454   and JavaScript).
4455
4456   Nested configuration flags:
4457
4458   Separator format of integer literals of different bases.
4459
4460   If negative, remove separators. If  ``0``, leave the literal as is. If
4461   positive, insert separators between digits starting from the rightmost
4462   digit.
4463
4464   For example, the config below will leave separators in binary literals
4465   alone, insert separators in decimal literals to separate the digits into
4466   groups of 3, and remove separators in hexadecimal literals.
4467
4468   .. code-block:: c++
4469
4470     IntegerLiteralSeparator:
4471       Binary: 0
4472       Decimal: 3
4473       Hex: -1
4474
4475   You can also specify a minimum number of digits (``BinaryMinDigits``,
4476   ``DecimalMinDigits``, and ``HexMinDigits``) the integer literal must
4477   have in order for the separators to be inserted.
4478
4479   * ``int8_t Binary`` Format separators in binary literals.
4480
4481     .. code-block:: text
4482
4483       /* -1: */ b = 0b100111101101;
4484       /*  0: */ b = 0b10011'11'0110'1;
4485       /*  3: */ b = 0b100'111'101'101;
4486       /*  4: */ b = 0b1001'1110'1101;
4487
4488   * ``int8_t BinaryMinDigits`` Format separators in binary literals with a minimum number of digits.
4489
4490     .. code-block:: text
4491
4492       // Binary: 3
4493       // BinaryMinDigits: 7
4494       b1 = 0b101101;
4495       b2 = 0b1'101'101;
4496
4497   * ``int8_t Decimal`` Format separators in decimal literals.
4498
4499     .. code-block:: text
4500
4501       /* -1: */ d = 18446744073709550592ull;
4502       /*  0: */ d = 184467'440737'0'95505'92ull;
4503       /*  3: */ d = 18'446'744'073'709'550'592ull;
4504
4505   * ``int8_t DecimalMinDigits`` Format separators in decimal literals with a minimum number of digits.
4506
4507     .. code-block:: text
4508
4509       // Decimal: 3
4510       // DecimalMinDigits: 5
4511       d1 = 2023;
4512       d2 = 10'000;
4513
4514   * ``int8_t Hex`` Format separators in hexadecimal literals.
4515
4516     .. code-block:: text
4517
4518       /* -1: */ h = 0xDEADBEEFDEADBEEFuz;
4519       /*  0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz;
4520       /*  2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz;
4521
4522   * ``int8_t HexMinDigits`` Format separators in hexadecimal literals with a minimum number of
4523     digits.
4524
4525     .. code-block:: text
4526
4527       // Hex: 2
4528       // HexMinDigits: 6
4529       h1 = 0xABCDE;
4530       h2 = 0xAB'CD'EF;
4531
4532
4533 .. _JavaImportGroups:
4534
4535 **JavaImportGroups** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <JavaImportGroups>`
4536   A vector of prefixes ordered by the desired groups for Java imports.
4537
4538   One group's prefix can be a subset of another - the longest prefix is
4539   always matched. Within a group, the imports are ordered lexicographically.
4540   Static imports are grouped separately and follow the same group rules.
4541   By default, static imports are placed before non-static imports,
4542   but this behavior is changed by another option,
4543   ``SortJavaStaticImport``.
4544
4545   In the .clang-format configuration file, this can be configured like
4546   in the following yaml example. This will result in imports being
4547   formatted as in the Java example below.
4548
4549   .. code-block:: yaml
4550
4551     JavaImportGroups: [com.example, com, org]
4552
4553
4554   .. code-block:: java
4555
4556      import static com.example.function1;
4557
4558      import static com.test.function2;
4559
4560      import static org.example.function3;
4561
4562      import com.example.ClassA;
4563      import com.example.Test;
4564      import com.example.a.ClassB;
4565
4566      import com.test.ClassC;
4567
4568      import org.example.ClassD;
4569
4570 .. _JavaScriptQuotes:
4571
4572 **JavaScriptQuotes** (``JavaScriptQuoteStyle``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptQuotes>`
4573   The JavaScriptQuoteStyle to use for JavaScript strings.
4574
4575   Possible values:
4576
4577   * ``JSQS_Leave`` (in configuration: ``Leave``)
4578     Leave string quotes as they are.
4579
4580     .. code-block:: js
4581
4582        string1 = "foo";
4583        string2 = 'bar';
4584
4585   * ``JSQS_Single`` (in configuration: ``Single``)
4586     Always use single quotes.
4587
4588     .. code-block:: js
4589
4590        string1 = 'foo';
4591        string2 = 'bar';
4592
4593   * ``JSQS_Double`` (in configuration: ``Double``)
4594     Always use double quotes.
4595
4596     .. code-block:: js
4597
4598        string1 = "foo";
4599        string2 = "bar";
4600
4601
4602
4603 .. _JavaScriptWrapImports:
4604
4605 **JavaScriptWrapImports** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptWrapImports>`
4606   Whether to wrap JavaScript import/export statements.
4607
4608   .. code-block:: js
4609
4610      true:
4611      import {
4612          VeryLongImportsAreAnnoying,
4613          VeryLongImportsAreAnnoying,
4614          VeryLongImportsAreAnnoying,
4615      } from "some/module.js"
4616
4617      false:
4618      import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
4619
4620 .. _KeepEmptyLines:
4621
4622 **KeepEmptyLines** (``KeepEmptyLinesStyle``) :versionbadge:`clang-format 19` :ref:`¶ <KeepEmptyLines>`
4623   Which empty lines are kept.  See ``MaxEmptyLinesToKeep`` for how many
4624   consecutive empty lines are kept.
4625
4626   Nested configuration flags:
4627
4628   Options regarding which empty lines are kept.
4629
4630   For example, the config below will remove empty lines at start of the
4631   file, end of the file, and start of blocks.
4632
4633
4634   .. code-block:: c++
4635
4636     KeepEmptyLines:
4637       AtEndOfFile: false
4638       AtStartOfBlock: false
4639       AtStartOfFile: false
4640
4641   * ``bool AtEndOfFile`` Keep empty lines at end of file.
4642
4643   * ``bool AtStartOfBlock`` Keep empty lines at start of a block.
4644
4645     .. code-block:: c++
4646
4647        true:                                  false:
4648        if (foo) {                     vs.     if (foo) {
4649                                                 bar();
4650          bar();                               }
4651        }
4652
4653   * ``bool AtStartOfFile`` Keep empty lines at start of file.
4654
4655
4656 .. _KeepEmptyLinesAtEOF:
4657
4658 **KeepEmptyLinesAtEOF** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <KeepEmptyLinesAtEOF>`
4659   This option is deprecated. See ``AtEndOfFile`` of ``KeepEmptyLines``.
4660
4661 .. _KeepEmptyLinesAtTheStartOfBlocks:
4662
4663 **KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <KeepEmptyLinesAtTheStartOfBlocks>`
4664   This option is deprecated. See ``AtStartOfBlock`` of ``KeepEmptyLines``.
4665
4666 .. _KeepFormFeed:
4667
4668 **KeepFormFeed** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <KeepFormFeed>`
4669   Keep the form feed character if it's immediately preceded and followed by
4670   a newline. Multiple form feeds and newlines within a whitespace range are
4671   replaced with a single newline and form feed followed by the remaining
4672   newlines.
4673
4674 .. _LambdaBodyIndentation:
4675
4676 **LambdaBodyIndentation** (``LambdaBodyIndentationKind``) :versionbadge:`clang-format 13` :ref:`¶ <LambdaBodyIndentation>`
4677   The indentation style of lambda bodies. ``Signature`` (the default)
4678   causes the lambda body to be indented one additional level relative to
4679   the indentation level of the signature. ``OuterScope`` forces the lambda
4680   body to be indented one additional level relative to the parent scope
4681   containing the lambda signature.
4682
4683   Possible values:
4684
4685   * ``LBI_Signature`` (in configuration: ``Signature``)
4686     Align lambda body relative to the lambda signature. This is the default.
4687
4688     .. code-block:: c++
4689
4690        someMethod(
4691            [](SomeReallyLongLambdaSignatureArgument foo) {
4692              return;
4693            });
4694
4695   * ``LBI_OuterScope`` (in configuration: ``OuterScope``)
4696     For statements within block scope, align lambda body relative to the
4697     indentation level of the outer scope the lambda signature resides in.
4698
4699     .. code-block:: c++
4700
4701        someMethod(
4702            [](SomeReallyLongLambdaSignatureArgument foo) {
4703          return;
4704        });
4705
4706        someMethod(someOtherMethod(
4707            [](SomeReallyLongLambdaSignatureArgument foo) {
4708          return;
4709        }));
4710
4711
4712
4713 .. _Language:
4714
4715 **Language** (``LanguageKind``) :versionbadge:`clang-format 3.5` :ref:`¶ <Language>`
4716   Language, this format style is targeted at.
4717
4718   Possible values:
4719
4720   * ``LK_None`` (in configuration: ``None``)
4721     Do not use.
4722
4723   * ``LK_Cpp`` (in configuration: ``Cpp``)
4724     Should be used for C, C++.
4725
4726   * ``LK_CSharp`` (in configuration: ``CSharp``)
4727     Should be used for C#.
4728
4729   * ``LK_Java`` (in configuration: ``Java``)
4730     Should be used for Java.
4731
4732   * ``LK_JavaScript`` (in configuration: ``JavaScript``)
4733     Should be used for JavaScript.
4734
4735   * ``LK_Json`` (in configuration: ``Json``)
4736     Should be used for JSON.
4737
4738   * ``LK_ObjC`` (in configuration: ``ObjC``)
4739     Should be used for Objective-C, Objective-C++.
4740
4741   * ``LK_Proto`` (in configuration: ``Proto``)
4742     Should be used for Protocol Buffers
4743     (https://developers.google.com/protocol-buffers/).
4744
4745   * ``LK_TableGen`` (in configuration: ``TableGen``)
4746     Should be used for TableGen code.
4747
4748   * ``LK_TextProto`` (in configuration: ``TextProto``)
4749     Should be used for Protocol Buffer messages in text format
4750     (https://developers.google.com/protocol-buffers/).
4751
4752   * ``LK_Verilog`` (in configuration: ``Verilog``)
4753     Should be used for Verilog and SystemVerilog.
4754     https://standards.ieee.org/ieee/1800/6700/
4755     https://sci-hub.st/10.1109/IEEESTD.2018.8299595
4756
4757
4758
4759 .. _LineEnding:
4760
4761 **LineEnding** (``LineEndingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <LineEnding>`
4762   Line ending style (``\n`` or ``\r\n``) to use.
4763
4764   Possible values:
4765
4766   * ``LE_LF`` (in configuration: ``LF``)
4767     Use ``\n``.
4768
4769   * ``LE_CRLF`` (in configuration: ``CRLF``)
4770     Use ``\r\n``.
4771
4772   * ``LE_DeriveLF`` (in configuration: ``DeriveLF``)
4773     Use ``\n`` unless the input has more lines ending in ``\r\n``.
4774
4775   * ``LE_DeriveCRLF`` (in configuration: ``DeriveCRLF``)
4776     Use ``\r\n`` unless the input has more lines ending in ``\n``.
4777
4778
4779
4780 .. _MacroBlockBegin:
4781
4782 **MacroBlockBegin** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockBegin>`
4783   A regular expression matching macros that start a block.
4784
4785   .. code-block:: c++
4786
4787      # With:
4788      MacroBlockBegin: "^NS_MAP_BEGIN|\
4789      NS_TABLE_HEAD$"
4790      MacroBlockEnd: "^\
4791      NS_MAP_END|\
4792      NS_TABLE_.*_END$"
4793
4794      NS_MAP_BEGIN
4795        foo();
4796      NS_MAP_END
4797
4798      NS_TABLE_HEAD
4799        bar();
4800      NS_TABLE_FOO_END
4801
4802      # Without:
4803      NS_MAP_BEGIN
4804      foo();
4805      NS_MAP_END
4806
4807      NS_TABLE_HEAD
4808      bar();
4809      NS_TABLE_FOO_END
4810
4811 .. _MacroBlockEnd:
4812
4813 **MacroBlockEnd** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockEnd>`
4814   A regular expression matching macros that end a block.
4815
4816 .. _Macros:
4817
4818 **Macros** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <Macros>`
4819   A list of macros of the form ``<definition>=<expansion>`` .
4820
4821   Code will be parsed with macros expanded, in order to determine how to
4822   interpret and format the macro arguments.
4823
4824   For example, the code:
4825
4826   .. code-block:: c++
4827
4828     A(a*b);
4829
4830   will usually be interpreted as a call to a function A, and the
4831   multiplication expression will be formatted as ``a * b``.
4832
4833   If we specify the macro definition:
4834
4835   .. code-block:: yaml
4836
4837     Macros:
4838     - A(x)=x
4839
4840   the code will now be parsed as a declaration of the variable b of type a*,
4841   and formatted as ``a* b`` (depending on pointer-binding rules).
4842
4843   Features and restrictions:
4844    * Both function-like macros and object-like macros are supported.
4845    * Macro arguments must be used exactly once in the expansion.
4846    * No recursive expansion; macros referencing other macros will be
4847      ignored.
4848    * Overloading by arity is supported: for example, given the macro
4849      definitions A=x, A()=y, A(a)=a
4850
4851
4852   .. code-block:: c++
4853
4854      A; -> x;
4855      A(); -> y;
4856      A(z); -> z;
4857      A(a, b); // will not be expanded.
4858
4859 .. _MainIncludeChar:
4860
4861 **MainIncludeChar** (``MainIncludeCharDiscriminator``) :versionbadge:`clang-format 19` :ref:`¶ <MainIncludeChar>`
4862   When guessing whether a #include is the "main" include, only the include
4863   directives that use the specified character are considered.
4864
4865   Possible values:
4866
4867   * ``MICD_Quote`` (in configuration: ``Quote``)
4868     Main include uses quotes: ``#include "foo.hpp"`` (the default).
4869
4870   * ``MICD_AngleBracket`` (in configuration: ``AngleBracket``)
4871     Main include uses angle brackets: ``#include <foo.hpp>``.
4872
4873   * ``MICD_Any`` (in configuration: ``Any``)
4874     Main include uses either quotes or angle brackets.
4875
4876
4877
4878 .. _MaxEmptyLinesToKeep:
4879
4880 **MaxEmptyLinesToKeep** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <MaxEmptyLinesToKeep>`
4881   The maximum number of consecutive empty lines to keep.
4882
4883   .. code-block:: c++
4884
4885      MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 0
4886      int f() {                              int f() {
4887        int = 1;                                 int i = 1;
4888                                                 i = foo();
4889        i = foo();                               return i;
4890                                             }
4891        return i;
4892      }
4893
4894 .. _NamespaceIndentation:
4895
4896 **NamespaceIndentation** (``NamespaceIndentationKind``) :versionbadge:`clang-format 3.7` :ref:`¶ <NamespaceIndentation>`
4897   The indentation used for namespaces.
4898
4899   Possible values:
4900
4901   * ``NI_None`` (in configuration: ``None``)
4902     Don't indent in namespaces.
4903
4904     .. code-block:: c++
4905
4906        namespace out {
4907        int i;
4908        namespace in {
4909        int i;
4910        }
4911        }
4912
4913   * ``NI_Inner`` (in configuration: ``Inner``)
4914     Indent only in inner namespaces (nested in other namespaces).
4915
4916     .. code-block:: c++
4917
4918        namespace out {
4919        int i;
4920        namespace in {
4921          int i;
4922        }
4923        }
4924
4925   * ``NI_All`` (in configuration: ``All``)
4926     Indent in all namespaces.
4927
4928     .. code-block:: c++
4929
4930        namespace out {
4931          int i;
4932          namespace in {
4933            int i;
4934          }
4935        }
4936
4937
4938
4939 .. _NamespaceMacros:
4940
4941 **NamespaceMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <NamespaceMacros>`
4942   A vector of macros which are used to open namespace blocks.
4943
4944   These are expected to be macros of the form:
4945
4946   .. code-block:: c++
4947
4948     NAMESPACE(<namespace-name>, ...) {
4949       <namespace-content>
4950     }
4951
4952   For example: TESTSUITE
4953
4954 .. _ObjCBinPackProtocolList:
4955
4956 **ObjCBinPackProtocolList** (``BinPackStyle``) :versionbadge:`clang-format 7` :ref:`¶ <ObjCBinPackProtocolList>`
4957   Controls bin-packing Objective-C protocol conformance list
4958   items into as few lines as possible when they go over ``ColumnLimit``.
4959
4960   If ``Auto`` (the default), delegates to the value in
4961   ``BinPackParameters``. If that is ``BinPack``, bin-packs Objective-C
4962   protocol conformance list items into as few lines as possible
4963   whenever they go over ``ColumnLimit``.
4964
4965   If ``Always``, always bin-packs Objective-C protocol conformance
4966   list items into as few lines as possible whenever they go over
4967   ``ColumnLimit``.
4968
4969   If ``Never``, lays out Objective-C protocol conformance list items
4970   onto individual lines whenever they go over ``ColumnLimit``.
4971
4972
4973   .. code-block:: objc
4974
4975      Always (or Auto, if BinPackParameters==BinPack):
4976      @interface ccccccccccccc () <
4977          ccccccccccccc, ccccccccccccc,
4978          ccccccccccccc, ccccccccccccc> {
4979      }
4980
4981      Never (or Auto, if BinPackParameters!=BinPack):
4982      @interface ddddddddddddd () <
4983          ddddddddddddd,
4984          ddddddddddddd,
4985          ddddddddddddd,
4986          ddddddddddddd> {
4987      }
4988
4989   Possible values:
4990
4991   * ``BPS_Auto`` (in configuration: ``Auto``)
4992     Automatically determine parameter bin-packing behavior.
4993
4994   * ``BPS_Always`` (in configuration: ``Always``)
4995     Always bin-pack parameters.
4996
4997   * ``BPS_Never`` (in configuration: ``Never``)
4998     Never bin-pack parameters.
4999
5000
5001
5002 .. _ObjCBlockIndentWidth:
5003
5004 **ObjCBlockIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCBlockIndentWidth>`
5005   The number of characters to use for indentation of ObjC blocks.
5006
5007   .. code-block:: objc
5008
5009      ObjCBlockIndentWidth: 4
5010
5011      [operation setCompletionBlock:^{
5012          [self onOperationDone];
5013      }];
5014
5015 .. _ObjCBreakBeforeNestedBlockParam:
5016
5017 **ObjCBreakBeforeNestedBlockParam** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <ObjCBreakBeforeNestedBlockParam>`
5018   Break parameters list into lines when there is nested block
5019   parameters in a function call.
5020
5021   .. code-block:: c++
5022
5023     false:
5024      - (void)_aMethod
5025      {
5026          [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
5027          *u, NSNumber *v) {
5028              u = c;
5029          }]
5030      }
5031      true:
5032      - (void)_aMethod
5033      {
5034         [self.test1 t:self
5035                      w:self
5036             callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
5037                  u = c;
5038              }]
5039      }
5040
5041 .. _ObjCPropertyAttributeOrder:
5042
5043 **ObjCPropertyAttributeOrder** (``List of Strings``) :versionbadge:`clang-format 18` :ref:`¶ <ObjCPropertyAttributeOrder>`
5044   The order in which ObjC property attributes should appear.
5045
5046   Attributes in code will be sorted in the order specified. Any attributes
5047   encountered that are not mentioned in this array will be sorted last, in
5048   stable order. Comments between attributes will leave the attributes
5049   untouched.
5050
5051   .. warning::
5052
5053    Using this option could lead to incorrect code formatting due to
5054    clang-format's lack of complete semantic information. As such, extra
5055    care should be taken to review code changes made by this option.
5056
5057   .. code-block:: yaml
5058
5059     ObjCPropertyAttributeOrder: [
5060         class, direct,
5061         atomic, nonatomic,
5062         assign, retain, strong, copy, weak, unsafe_unretained,
5063         readonly, readwrite, getter, setter,
5064         nullable, nonnull, null_resettable, null_unspecified
5065     ]
5066
5067 .. _ObjCSpaceAfterProperty:
5068
5069 **ObjCSpaceAfterProperty** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceAfterProperty>`
5070   Add a space after ``@property`` in Objective-C, i.e. use
5071   ``@property (readonly)`` instead of ``@property(readonly)``.
5072
5073 .. _ObjCSpaceBeforeProtocolList:
5074
5075 **ObjCSpaceBeforeProtocolList** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceBeforeProtocolList>`
5076   Add a space in front of an Objective-C protocol list, i.e. use
5077   ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
5078
5079 .. _PPIndentWidth:
5080
5081 **PPIndentWidth** (``Integer``) :versionbadge:`clang-format 13` :ref:`¶ <PPIndentWidth>`
5082   The number of columns to use for indentation of preprocessor statements.
5083   When set to -1 (default) ``IndentWidth`` is used also for preprocessor
5084   statements.
5085
5086   .. code-block:: c++
5087
5088      PPIndentWidth: 1
5089
5090      #ifdef __linux__
5091      # define FOO
5092      #else
5093      # define BAR
5094      #endif
5095
5096 .. _PackConstructorInitializers:
5097
5098 **PackConstructorInitializers** (``PackConstructorInitializersStyle``) :versionbadge:`clang-format 14` :ref:`¶ <PackConstructorInitializers>`
5099   The pack constructor initializers style to use.
5100
5101   Possible values:
5102
5103   * ``PCIS_Never`` (in configuration: ``Never``)
5104     Always put each constructor initializer on its own line.
5105
5106     .. code-block:: c++
5107
5108        Constructor()
5109            : a(),
5110              b()
5111
5112   * ``PCIS_BinPack`` (in configuration: ``BinPack``)
5113     Bin-pack constructor initializers.
5114
5115     .. code-block:: c++
5116
5117        Constructor()
5118            : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(),
5119              cccccccccccccccccccc()
5120
5121   * ``PCIS_CurrentLine`` (in configuration: ``CurrentLine``)
5122     Put all constructor initializers on the current line if they fit.
5123     Otherwise, put each one on its own line.
5124
5125     .. code-block:: c++
5126
5127        Constructor() : a(), b()
5128
5129        Constructor()
5130            : aaaaaaaaaaaaaaaaaaaa(),
5131              bbbbbbbbbbbbbbbbbbbb(),
5132              ddddddddddddd()
5133
5134   * ``PCIS_NextLine`` (in configuration: ``NextLine``)
5135     Same as ``PCIS_CurrentLine`` except that if all constructor initializers
5136     do not fit on the current line, try to fit them on the next line.
5137
5138     .. code-block:: c++
5139
5140        Constructor() : a(), b()
5141
5142        Constructor()
5143            : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
5144
5145        Constructor()
5146            : aaaaaaaaaaaaaaaaaaaa(),
5147              bbbbbbbbbbbbbbbbbbbb(),
5148              cccccccccccccccccccc()
5149
5150   * ``PCIS_NextLineOnly`` (in configuration: ``NextLineOnly``)
5151     Put all constructor initializers on the next line if they fit.
5152     Otherwise, put each one on its own line.
5153
5154     .. code-block:: c++
5155
5156        Constructor()
5157            : a(), b()
5158
5159        Constructor()
5160            : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
5161
5162        Constructor()
5163            : aaaaaaaaaaaaaaaaaaaa(),
5164              bbbbbbbbbbbbbbbbbbbb(),
5165              cccccccccccccccccccc()
5166
5167
5168
5169 .. _PenaltyBreakAssignment:
5170
5171 **PenaltyBreakAssignment** (``Unsigned``) :versionbadge:`clang-format 5` :ref:`¶ <PenaltyBreakAssignment>`
5172   The penalty for breaking around an assignment operator.
5173
5174 .. _PenaltyBreakBeforeFirstCallParameter:
5175
5176 **PenaltyBreakBeforeFirstCallParameter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakBeforeFirstCallParameter>`
5177   The penalty for breaking a function call after ``call(``.
5178
5179 .. _PenaltyBreakComment:
5180
5181 **PenaltyBreakComment** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakComment>`
5182   The penalty for each line break introduced inside a comment.
5183
5184 .. _PenaltyBreakFirstLessLess:
5185
5186 **PenaltyBreakFirstLessLess** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakFirstLessLess>`
5187   The penalty for breaking before the first ``<<``.
5188
5189 .. _PenaltyBreakOpenParenthesis:
5190
5191 **PenaltyBreakOpenParenthesis** (``Unsigned``) :versionbadge:`clang-format 14` :ref:`¶ <PenaltyBreakOpenParenthesis>`
5192   The penalty for breaking after ``(``.
5193
5194 .. _PenaltyBreakScopeResolution:
5195
5196 **PenaltyBreakScopeResolution** (``Unsigned``) :versionbadge:`clang-format 18` :ref:`¶ <PenaltyBreakScopeResolution>`
5197   The penalty for breaking after ``::``.
5198
5199 .. _PenaltyBreakString:
5200
5201 **PenaltyBreakString** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakString>`
5202   The penalty for each line break introduced inside a string literal.
5203
5204 .. _PenaltyBreakTemplateDeclaration:
5205
5206 **PenaltyBreakTemplateDeclaration** (``Unsigned``) :versionbadge:`clang-format 7` :ref:`¶ <PenaltyBreakTemplateDeclaration>`
5207   The penalty for breaking after template declaration.
5208
5209 .. _PenaltyExcessCharacter:
5210
5211 **PenaltyExcessCharacter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyExcessCharacter>`
5212   The penalty for each character outside of the column limit.
5213
5214 .. _PenaltyIndentedWhitespace:
5215
5216 **PenaltyIndentedWhitespace** (``Unsigned``) :versionbadge:`clang-format 12` :ref:`¶ <PenaltyIndentedWhitespace>`
5217   Penalty for each character of whitespace indentation
5218   (counted relative to leading non-whitespace column).
5219
5220 .. _PenaltyReturnTypeOnItsOwnLine:
5221
5222 **PenaltyReturnTypeOnItsOwnLine** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyReturnTypeOnItsOwnLine>`
5223   Penalty for putting the return type of a function onto its own line.
5224
5225 .. _PointerAlignment:
5226
5227 **PointerAlignment** (``PointerAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <PointerAlignment>`
5228   Pointer and reference alignment style.
5229
5230   Possible values:
5231
5232   * ``PAS_Left`` (in configuration: ``Left``)
5233     Align pointer to the left.
5234
5235     .. code-block:: c++
5236
5237       int* a;
5238
5239   * ``PAS_Right`` (in configuration: ``Right``)
5240     Align pointer to the right.
5241
5242     .. code-block:: c++
5243
5244       int *a;
5245
5246   * ``PAS_Middle`` (in configuration: ``Middle``)
5247     Align pointer in the middle.
5248
5249     .. code-block:: c++
5250
5251       int * a;
5252
5253
5254
5255 .. _QualifierAlignment:
5256
5257 **QualifierAlignment** (``QualifierAlignmentStyle``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierAlignment>`
5258   Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
5259
5260   .. warning::
5261
5262    Setting ``QualifierAlignment``  to something other than ``Leave``, COULD
5263    lead to incorrect code formatting due to incorrect decisions made due to
5264    clang-formats lack of complete semantic information.
5265    As such extra care should be taken to review code changes made by the use
5266    of this option.
5267
5268   Possible values:
5269
5270   * ``QAS_Leave`` (in configuration: ``Leave``)
5271     Don't change specifiers/qualifiers to either Left or Right alignment
5272     (default).
5273
5274     .. code-block:: c++
5275
5276        int const a;
5277        const int *a;
5278
5279   * ``QAS_Left`` (in configuration: ``Left``)
5280     Change specifiers/qualifiers to be left-aligned.
5281
5282     .. code-block:: c++
5283
5284        const int a;
5285        const int *a;
5286
5287   * ``QAS_Right`` (in configuration: ``Right``)
5288     Change specifiers/qualifiers to be right-aligned.
5289
5290     .. code-block:: c++
5291
5292        int const a;
5293        int const *a;
5294
5295   * ``QAS_Custom`` (in configuration: ``Custom``)
5296     Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
5297     With:
5298
5299     .. code-block:: yaml
5300
5301       QualifierOrder: [inline, static, type, const]
5302
5303
5304     .. code-block:: c++
5305
5306
5307        int const a;
5308        int const *a;
5309
5310
5311
5312 .. _QualifierOrder:
5313
5314 **QualifierOrder** (``List of Strings``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierOrder>`
5315   The order in which the qualifiers appear.
5316   Order is an array that can contain any of the following:
5317
5318     * const
5319     * inline
5320     * static
5321     * friend
5322     * constexpr
5323     * volatile
5324     * restrict
5325     * type
5326
5327
5328   .. note::
5329
5330    It **must** contain ``type``.
5331
5332   Items to the left of ``type`` will be placed to the left of the type and
5333   aligned in the order supplied. Items to the right of ``type`` will be
5334   placed to the right of the type and aligned in the order supplied.
5335
5336
5337   .. code-block:: yaml
5338
5339     QualifierOrder: [inline, static, type, const, volatile]
5340
5341 .. _RawStringFormats:
5342
5343 **RawStringFormats** (``List of RawStringFormats``) :versionbadge:`clang-format 6` :ref:`¶ <RawStringFormats>`
5344   Defines hints for detecting supported languages code blocks in raw
5345   strings.
5346
5347   A raw string with a matching delimiter or a matching enclosing function
5348   name will be reformatted assuming the specified language based on the
5349   style for that language defined in the .clang-format file. If no style has
5350   been defined in the .clang-format file for the specific language, a
5351   predefined style given by ``BasedOnStyle`` is used. If ``BasedOnStyle`` is
5352   not found, the formatting is based on ``LLVM`` style. A matching delimiter
5353   takes precedence over a matching enclosing function name for determining
5354   the language of the raw string contents.
5355
5356   If a canonical delimiter is specified, occurrences of other delimiters for
5357   the same language will be updated to the canonical if possible.
5358
5359   There should be at most one specification per language and each delimiter
5360   and enclosing function should not occur in multiple specifications.
5361
5362   To configure this in the .clang-format file, use:
5363
5364   .. code-block:: yaml
5365
5366     RawStringFormats:
5367       - Language: TextProto
5368           Delimiters:
5369             - pb
5370             - proto
5371           EnclosingFunctions:
5372             - PARSE_TEXT_PROTO
5373           BasedOnStyle: google
5374       - Language: Cpp
5375           Delimiters:
5376             - cc
5377             - cpp
5378           BasedOnStyle: LLVM
5379           CanonicalDelimiter: cc
5380
5381 .. _ReferenceAlignment:
5382
5383 **ReferenceAlignment** (``ReferenceAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <ReferenceAlignment>`
5384   Reference alignment style (overrides ``PointerAlignment`` for
5385   references).
5386
5387   Possible values:
5388
5389   * ``RAS_Pointer`` (in configuration: ``Pointer``)
5390     Align reference like ``PointerAlignment``.
5391
5392   * ``RAS_Left`` (in configuration: ``Left``)
5393     Align reference to the left.
5394
5395     .. code-block:: c++
5396
5397       int& a;
5398
5399   * ``RAS_Right`` (in configuration: ``Right``)
5400     Align reference to the right.
5401
5402     .. code-block:: c++
5403
5404       int &a;
5405
5406   * ``RAS_Middle`` (in configuration: ``Middle``)
5407     Align reference in the middle.
5408
5409     .. code-block:: c++
5410
5411       int & a;
5412
5413
5414
5415 .. _ReflowComments:
5416
5417 **ReflowComments** (``ReflowCommentsStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <ReflowComments>`
5418   Comment reformatting style.
5419
5420   Possible values:
5421
5422   * ``RCS_Never`` (in configuration: ``Never``)
5423     Leave comments untouched.
5424
5425     .. code-block:: c++
5426
5427        // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
5428        /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
5429        /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
5430             * and a misaligned second line */
5431
5432   * ``RCS_IndentOnly`` (in configuration: ``IndentOnly``)
5433     Only apply indentation rules, moving comments left or right, without
5434     changing formatting inside the comments.
5435
5436     .. code-block:: c++
5437
5438        // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
5439        /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
5440        /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
5441         * and a misaligned second line */
5442
5443   * ``RCS_Always`` (in configuration: ``Always``)
5444     Apply indentation rules and reflow long comments into new lines, trying
5445     to obey the ``ColumnLimit``.
5446
5447     .. code-block:: c++
5448
5449        // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
5450        // information
5451        /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
5452         * information */
5453        /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
5454         * information and a misaligned second line */
5455
5456
5457
5458 .. _RemoveBracesLLVM:
5459
5460 **RemoveBracesLLVM** (``Boolean``) :versionbadge:`clang-format 14` :ref:`¶ <RemoveBracesLLVM>`
5461   Remove optional braces of control statements (``if``, ``else``, ``for``,
5462   and ``while``) in C++ according to the LLVM coding style.
5463
5464   .. warning::
5465
5466    This option will be renamed and expanded to support other styles.
5467
5468   .. warning::
5469
5470    Setting this option to ``true`` could lead to incorrect code formatting
5471    due to clang-format's lack of complete semantic information. As such,
5472    extra care should be taken to review code changes made by this option.
5473
5474   .. code-block:: c++
5475
5476     false:                                     true:
5477
5478     if (isa<FunctionDecl>(D)) {        vs.     if (isa<FunctionDecl>(D))
5479       handleFunctionDecl(D);                     handleFunctionDecl(D);
5480     } else if (isa<VarDecl>(D)) {              else if (isa<VarDecl>(D))
5481       handleVarDecl(D);                          handleVarDecl(D);
5482     }
5483
5484     if (isa<VarDecl>(D)) {             vs.     if (isa<VarDecl>(D)) {
5485       for (auto *A : D.attrs()) {                for (auto *A : D.attrs())
5486         if (shouldProcessAttr(A)) {                if (shouldProcessAttr(A))
5487           handleAttr(A);                             handleAttr(A);
5488         }                                      }
5489       }
5490     }
5491
5492     if (isa<FunctionDecl>(D)) {        vs.     if (isa<FunctionDecl>(D))
5493       for (auto *A : D.attrs()) {                for (auto *A : D.attrs())
5494         handleAttr(A);                             handleAttr(A);
5495       }
5496     }
5497
5498     if (auto *D = (T)(D)) {            vs.     if (auto *D = (T)(D)) {
5499       if (shouldProcess(D)) {                    if (shouldProcess(D))
5500         handleVarDecl(D);                          handleVarDecl(D);
5501       } else {                                   else
5502         markAsIgnored(D);                          markAsIgnored(D);
5503       }                                        }
5504     }
5505
5506     if (a) {                           vs.     if (a)
5507       b();                                       b();
5508     } else {                                   else if (c)
5509       if (c) {                                   d();
5510         d();                                   else
5511       } else {                                   e();
5512         e();
5513       }
5514     }
5515
5516 .. _RemoveEmptyLinesInUnwrappedLines:
5517
5518 **RemoveEmptyLinesInUnwrappedLines** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <RemoveEmptyLinesInUnwrappedLines>`
5519   Remove empty lines within unwrapped lines.
5520
5521   .. code-block:: c++
5522
5523     false:                            true:
5524
5525     int c                  vs.        int c = a + b;
5526
5527         = a + b;
5528
5529     enum : unsigned        vs.        enum : unsigned {
5530                                         AA = 0,
5531     {                                   BB
5532       AA = 0,                         } myEnum;
5533       BB
5534     } myEnum;
5535
5536     while (                vs.        while (true) {
5537                                       }
5538         true) {
5539     }
5540
5541 .. _RemoveParentheses:
5542
5543 **RemoveParentheses** (``RemoveParenthesesStyle``) :versionbadge:`clang-format 17` :ref:`¶ <RemoveParentheses>`
5544   Remove redundant parentheses.
5545
5546   .. warning::
5547
5548    Setting this option to any value other than ``Leave`` could lead to
5549    incorrect code formatting due to clang-format's lack of complete semantic
5550    information. As such, extra care should be taken to review code changes
5551    made by this option.
5552
5553   Possible values:
5554
5555   * ``RPS_Leave`` (in configuration: ``Leave``)
5556     Do not remove parentheses.
5557
5558     .. code-block:: c++
5559
5560       class __declspec((dllimport)) X {};
5561       co_return (((0)));
5562       return ((a + b) - ((c + d)));
5563
5564   * ``RPS_MultipleParentheses`` (in configuration: ``MultipleParentheses``)
5565     Replace multiple parentheses with single parentheses.
5566
5567     .. code-block:: c++
5568
5569       class __declspec(dllimport) X {};
5570       co_return (0);
5571       return ((a + b) - (c + d));
5572
5573   * ``RPS_ReturnStatement`` (in configuration: ``ReturnStatement``)
5574     Also remove parentheses enclosing the expression in a
5575     ``return``/``co_return`` statement.
5576
5577     .. code-block:: c++
5578
5579       class __declspec(dllimport) X {};
5580       co_return 0;
5581       return (a + b) - (c + d);
5582
5583
5584
5585 .. _RemoveSemicolon:
5586
5587 **RemoveSemicolon** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <RemoveSemicolon>`
5588   Remove semicolons after the closing braces of functions and
5589   constructors/destructors.
5590
5591   .. warning::
5592
5593    Setting this option to ``true`` could lead to incorrect code formatting
5594    due to clang-format's lack of complete semantic information. As such,
5595    extra care should be taken to review code changes made by this option.
5596
5597   .. code-block:: c++
5598
5599     false:                                     true:
5600
5601     int max(int a, int b) {                    int max(int a, int b) {
5602       return a > b ? a : b;                      return a > b ? a : b;
5603     };                                         }
5604
5605 .. _RequiresClausePosition:
5606
5607 **RequiresClausePosition** (``RequiresClausePositionStyle``) :versionbadge:`clang-format 15` :ref:`¶ <RequiresClausePosition>`
5608   The position of the ``requires`` clause.
5609
5610   Possible values:
5611
5612   * ``RCPS_OwnLine`` (in configuration: ``OwnLine``)
5613     Always put the ``requires`` clause on its own line (possibly followed by
5614     a semicolon).
5615
5616     .. code-block:: c++
5617
5618       template <typename T>
5619         requires C<T>
5620       struct Foo {...
5621
5622       template <typename T>
5623       void bar(T t)
5624         requires C<T>;
5625
5626       template <typename T>
5627         requires C<T>
5628       void bar(T t) {...
5629
5630       template <typename T>
5631       void baz(T t)
5632         requires C<T>
5633       {...
5634
5635   * ``RCPS_OwnLineWithBrace`` (in configuration: ``OwnLineWithBrace``)
5636     As with ``OwnLine``, except, unless otherwise prohibited, place a
5637     following open brace (of a function definition) to follow on the same
5638     line.
5639
5640     .. code-block:: c++
5641
5642       void bar(T t)
5643         requires C<T> {
5644         return;
5645       }
5646
5647       void bar(T t)
5648         requires C<T> {}
5649
5650       template <typename T>
5651         requires C<T>
5652       void baz(T t) {
5653         ...
5654
5655   * ``RCPS_WithPreceding`` (in configuration: ``WithPreceding``)
5656     Try to put the clause together with the preceding part of a declaration.
5657     For class templates: stick to the template declaration.
5658     For function templates: stick to the template declaration.
5659     For function declaration followed by a requires clause: stick to the
5660     parameter list.
5661
5662     .. code-block:: c++
5663
5664       template <typename T> requires C<T>
5665       struct Foo {...
5666
5667       template <typename T> requires C<T>
5668       void bar(T t) {...
5669
5670       template <typename T>
5671       void baz(T t) requires C<T>
5672       {...
5673
5674   * ``RCPS_WithFollowing`` (in configuration: ``WithFollowing``)
5675     Try to put the ``requires`` clause together with the class or function
5676     declaration.
5677
5678     .. code-block:: c++
5679
5680       template <typename T>
5681       requires C<T> struct Foo {...
5682
5683       template <typename T>
5684       requires C<T> void bar(T t) {...
5685
5686       template <typename T>
5687       void baz(T t)
5688       requires C<T> {...
5689
5690   * ``RCPS_SingleLine`` (in configuration: ``SingleLine``)
5691     Try to put everything in the same line if possible. Otherwise normal
5692     line breaking rules take over.
5693
5694     .. code-block:: c++
5695
5696       // Fitting:
5697       template <typename T> requires C<T> struct Foo {...
5698
5699       template <typename T> requires C<T> void bar(T t) {...
5700
5701       template <typename T> void bar(T t) requires C<T> {...
5702
5703       // Not fitting, one possible example:
5704       template <typename LongName>
5705       requires C<LongName>
5706       struct Foo {...
5707
5708       template <typename LongName>
5709       requires C<LongName>
5710       void bar(LongName ln) {
5711
5712       template <typename LongName>
5713       void bar(LongName ln)
5714           requires C<LongName> {
5715
5716
5717
5718 .. _RequiresExpressionIndentation:
5719
5720 **RequiresExpressionIndentation** (``RequiresExpressionIndentationKind``) :versionbadge:`clang-format 16` :ref:`¶ <RequiresExpressionIndentation>`
5721   The indentation used for requires expression bodies.
5722
5723   Possible values:
5724
5725   * ``REI_OuterScope`` (in configuration: ``OuterScope``)
5726     Align requires expression body relative to the indentation level of the
5727     outer scope the requires expression resides in.
5728     This is the default.
5729
5730     .. code-block:: c++
5731
5732        template <typename T>
5733        concept C = requires(T t) {
5734          ...
5735        }
5736
5737   * ``REI_Keyword`` (in configuration: ``Keyword``)
5738     Align requires expression body relative to the ``requires`` keyword.
5739
5740     .. code-block:: c++
5741
5742        template <typename T>
5743        concept C = requires(T t) {
5744                      ...
5745                    }
5746
5747
5748
5749 .. _SeparateDefinitionBlocks:
5750
5751 **SeparateDefinitionBlocks** (``SeparateDefinitionStyle``) :versionbadge:`clang-format 14` :ref:`¶ <SeparateDefinitionBlocks>`
5752   Specifies the use of empty lines to separate definition blocks, including
5753   classes, structs, enums, and functions.
5754
5755   .. code-block:: c++
5756
5757      Never                  v.s.     Always
5758      #include <cstring>              #include <cstring>
5759      struct Foo {
5760        int a, b, c;                  struct Foo {
5761      };                                int a, b, c;
5762      namespace Ns {                  };
5763      class Bar {
5764      public:                         namespace Ns {
5765        struct Foobar {               class Bar {
5766          int a;                      public:
5767          int b;                        struct Foobar {
5768        };                                int a;
5769      private:                            int b;
5770        int t;                          };
5771        int method1() {
5772          // ...                      private:
5773        }                               int t;
5774        enum List {
5775          ITEM1,                        int method1() {
5776          ITEM2                           // ...
5777        };                              }
5778        template<typename T>
5779        int method2(T x) {              enum List {
5780          // ...                          ITEM1,
5781        }                                 ITEM2
5782        int i, j, k;                    };
5783        int method3(int par) {
5784          // ...                        template<typename T>
5785        }                               int method2(T x) {
5786      };                                  // ...
5787      class C {};                       }
5788      }
5789                                        int i, j, k;
5790
5791                                        int method3(int par) {
5792                                          // ...
5793                                        }
5794                                      };
5795
5796                                      class C {};
5797                                      }
5798
5799   Possible values:
5800
5801   * ``SDS_Leave`` (in configuration: ``Leave``)
5802     Leave definition blocks as they are.
5803
5804   * ``SDS_Always`` (in configuration: ``Always``)
5805     Insert an empty line between definition blocks.
5806
5807   * ``SDS_Never`` (in configuration: ``Never``)
5808     Remove any empty line between definition blocks.
5809
5810
5811
5812 .. _ShortNamespaceLines:
5813
5814 **ShortNamespaceLines** (``Unsigned``) :versionbadge:`clang-format 13` :ref:`¶ <ShortNamespaceLines>`
5815   The maximal number of unwrapped lines that a short namespace spans.
5816   Defaults to 1.
5817
5818   This determines the maximum length of short namespaces by counting
5819   unwrapped lines (i.e. containing neither opening nor closing
5820   namespace brace) and makes ``FixNamespaceComments`` omit adding
5821   end comments for those.
5822
5823   .. code-block:: c++
5824
5825      ShortNamespaceLines: 1     vs.     ShortNamespaceLines: 0
5826      namespace a {                      namespace a {
5827        int foo;                           int foo;
5828      }                                  } // namespace a
5829
5830      ShortNamespaceLines: 1     vs.     ShortNamespaceLines: 0
5831      namespace b {                      namespace b {
5832        int foo;                           int foo;
5833        int bar;                           int bar;
5834      } // namespace b                   } // namespace b
5835
5836 .. _SkipMacroDefinitionBody:
5837
5838 **SkipMacroDefinitionBody** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <SkipMacroDefinitionBody>`
5839   Do not format macro definition body.
5840
5841 .. _SortIncludes:
5842
5843 **SortIncludes** (``SortIncludesOptions``) :versionbadge:`clang-format 3.8` :ref:`¶ <SortIncludes>`
5844   Controls if and how clang-format will sort ``#includes``.
5845
5846   Possible values:
5847
5848   * ``SI_Never`` (in configuration: ``Never``)
5849     Includes are never sorted.
5850
5851     .. code-block:: c++
5852
5853        #include "B/A.h"
5854        #include "A/B.h"
5855        #include "a/b.h"
5856        #include "A/b.h"
5857        #include "B/a.h"
5858
5859   * ``SI_CaseSensitive`` (in configuration: ``CaseSensitive``)
5860     Includes are sorted in an ASCIIbetical or case sensitive fashion.
5861
5862     .. code-block:: c++
5863
5864        #include "A/B.h"
5865        #include "A/b.h"
5866        #include "B/A.h"
5867        #include "B/a.h"
5868        #include "a/b.h"
5869
5870   * ``SI_CaseInsensitive`` (in configuration: ``CaseInsensitive``)
5871     Includes are sorted in an alphabetical or case insensitive fashion.
5872
5873     .. code-block:: c++
5874
5875        #include "A/B.h"
5876        #include "A/b.h"
5877        #include "a/b.h"
5878        #include "B/A.h"
5879        #include "B/a.h"
5880
5881
5882
5883 .. _SortJavaStaticImport:
5884
5885 **SortJavaStaticImport** (``SortJavaStaticImportOptions``) :versionbadge:`clang-format 12` :ref:`¶ <SortJavaStaticImport>`
5886   When sorting Java imports, by default static imports are placed before
5887   non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
5888   static imports are placed after non-static imports.
5889
5890   Possible values:
5891
5892   * ``SJSIO_Before`` (in configuration: ``Before``)
5893     Static imports are placed before non-static imports.
5894
5895     .. code-block:: java
5896
5897       import static org.example.function1;
5898
5899       import org.example.ClassA;
5900
5901   * ``SJSIO_After`` (in configuration: ``After``)
5902     Static imports are placed after non-static imports.
5903
5904     .. code-block:: java
5905
5906       import org.example.ClassA;
5907
5908       import static org.example.function1;
5909
5910
5911
5912 .. _SortUsingDeclarations:
5913
5914 **SortUsingDeclarations** (``SortUsingDeclarationsOptions``) :versionbadge:`clang-format 5` :ref:`¶ <SortUsingDeclarations>`
5915   Controls if and how clang-format will sort using declarations.
5916
5917   Possible values:
5918
5919   * ``SUD_Never`` (in configuration: ``Never``)
5920     Using declarations are never sorted.
5921
5922     .. code-block:: c++
5923
5924        using std::chrono::duration_cast;
5925        using std::move;
5926        using boost::regex;
5927        using boost::regex_constants::icase;
5928        using std::string;
5929
5930   * ``SUD_Lexicographic`` (in configuration: ``Lexicographic``)
5931     Using declarations are sorted in the order defined as follows:
5932     Split the strings by ``::`` and discard any initial empty strings. Sort
5933     the lists of names lexicographically, and within those groups, names are
5934     in case-insensitive lexicographic order.
5935
5936     .. code-block:: c++
5937
5938        using boost::regex;
5939        using boost::regex_constants::icase;
5940        using std::chrono::duration_cast;
5941        using std::move;
5942        using std::string;
5943
5944   * ``SUD_LexicographicNumeric`` (in configuration: ``LexicographicNumeric``)
5945     Using declarations are sorted in the order defined as follows:
5946     Split the strings by ``::`` and discard any initial empty strings. The
5947     last element of each list is a non-namespace name; all others are
5948     namespace names. Sort the lists of names lexicographically, where the
5949     sort order of individual names is that all non-namespace names come
5950     before all namespace names, and within those groups, names are in
5951     case-insensitive lexicographic order.
5952
5953     .. code-block:: c++
5954
5955        using boost::regex;
5956        using boost::regex_constants::icase;
5957        using std::move;
5958        using std::string;
5959        using std::chrono::duration_cast;
5960
5961
5962
5963 .. _SpaceAfterCStyleCast:
5964
5965 **SpaceAfterCStyleCast** (``Boolean``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceAfterCStyleCast>`
5966   If ``true``, a space is inserted after C style casts.
5967
5968   .. code-block:: c++
5969
5970      true:                                  false:
5971      (int) i;                       vs.     (int)i;
5972
5973 .. _SpaceAfterLogicalNot:
5974
5975 **SpaceAfterLogicalNot** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <SpaceAfterLogicalNot>`
5976   If ``true``, a space is inserted after the logical not operator (``!``).
5977
5978   .. code-block:: c++
5979
5980      true:                                  false:
5981      ! someExpression();            vs.     !someExpression();
5982
5983 .. _SpaceAfterTemplateKeyword:
5984
5985 **SpaceAfterTemplateKeyword** (``Boolean``) :versionbadge:`clang-format 4` :ref:`¶ <SpaceAfterTemplateKeyword>`
5986   If ``true``, a space will be inserted after the ``template`` keyword.
5987
5988   .. code-block:: c++
5989
5990      true:                                  false:
5991      template <int> void foo();     vs.     template<int> void foo();
5992
5993 .. _SpaceAroundPointerQualifiers:
5994
5995 **SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceAroundPointerQualifiers>`
5996   Defines in which cases to put a space before or after pointer qualifiers
5997
5998   Possible values:
5999
6000   * ``SAPQ_Default`` (in configuration: ``Default``)
6001     Don't ensure spaces around pointer qualifiers and use PointerAlignment
6002     instead.
6003
6004     .. code-block:: c++
6005
6006        PointerAlignment: Left                 PointerAlignment: Right
6007        void* const* x = NULL;         vs.     void *const *x = NULL;
6008
6009   * ``SAPQ_Before`` (in configuration: ``Before``)
6010     Ensure that there is a space before pointer qualifiers.
6011
6012     .. code-block:: c++
6013
6014        PointerAlignment: Left                 PointerAlignment: Right
6015        void* const* x = NULL;         vs.     void * const *x = NULL;
6016
6017   * ``SAPQ_After`` (in configuration: ``After``)
6018     Ensure that there is a space after pointer qualifiers.
6019
6020     .. code-block:: c++
6021
6022        PointerAlignment: Left                 PointerAlignment: Right
6023        void* const * x = NULL;         vs.     void *const *x = NULL;
6024
6025   * ``SAPQ_Both`` (in configuration: ``Both``)
6026     Ensure that there is a space both before and after pointer qualifiers.
6027
6028     .. code-block:: c++
6029
6030        PointerAlignment: Left                 PointerAlignment: Right
6031        void* const * x = NULL;         vs.     void * const *x = NULL;
6032
6033
6034
6035 .. _SpaceBeforeAssignmentOperators:
6036
6037 **SpaceBeforeAssignmentOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceBeforeAssignmentOperators>`
6038   If ``false``, spaces will be removed before assignment operators.
6039
6040   .. code-block:: c++
6041
6042      true:                                  false:
6043      int a = 5;                     vs.     int a= 5;
6044      a += 42;                               a+= 42;
6045
6046 .. _SpaceBeforeCaseColon:
6047
6048 **SpaceBeforeCaseColon** (``Boolean``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceBeforeCaseColon>`
6049   If ``false``, spaces will be removed before case colon.
6050
6051   .. code-block:: c++
6052
6053     true:                                   false
6054     switch (x) {                    vs.     switch (x) {
6055       case 1 : break;                         case 1: break;
6056     }                                       }
6057
6058 .. _SpaceBeforeCpp11BracedList:
6059
6060 **SpaceBeforeCpp11BracedList** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCpp11BracedList>`
6061   If ``true``, a space will be inserted before a C++11 braced list
6062   used to initialize an object (after the preceding identifier or type).
6063
6064   .. code-block:: c++
6065
6066      true:                                  false:
6067      Foo foo { bar };               vs.     Foo foo{ bar };
6068      Foo {};                                Foo{};
6069      vector<int> { 1, 2, 3 };               vector<int>{ 1, 2, 3 };
6070      new int[3] { 1, 2, 3 };                new int[3]{ 1, 2, 3 };
6071
6072 .. _SpaceBeforeCtorInitializerColon:
6073
6074 **SpaceBeforeCtorInitializerColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCtorInitializerColon>`
6075   If ``false``, spaces will be removed before constructor initializer
6076   colon.
6077
6078   .. code-block:: c++
6079
6080      true:                                  false:
6081      Foo::Foo() : a(a) {}                   Foo::Foo(): a(a) {}
6082
6083 .. _SpaceBeforeInheritanceColon:
6084
6085 **SpaceBeforeInheritanceColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeInheritanceColon>`
6086   If ``false``, spaces will be removed before inheritance colon.
6087
6088   .. code-block:: c++
6089
6090      true:                                  false:
6091      class Foo : Bar {}             vs.     class Foo: Bar {}
6092
6093 .. _SpaceBeforeJsonColon:
6094
6095 **SpaceBeforeJsonColon** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <SpaceBeforeJsonColon>`
6096   If ``true``, a space will be added before a JSON colon. For other
6097   languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead.
6098
6099   .. code-block:: c++
6100
6101      true:                                  false:
6102      {                                      {
6103        "key" : "value"              vs.       "key": "value"
6104      }                                      }
6105
6106 .. _SpaceBeforeParens:
6107
6108 **SpaceBeforeParens** (``SpaceBeforeParensStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceBeforeParens>`
6109   Defines in which cases to put a space before opening parentheses.
6110
6111   Possible values:
6112
6113   * ``SBPO_Never`` (in configuration: ``Never``)
6114     This is **deprecated** and replaced by ``Custom`` below, with all
6115     ``SpaceBeforeParensOptions`` but ``AfterPlacementOperator`` set to
6116     ``false``.
6117
6118   * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
6119     Put a space before opening parentheses only after control statement
6120     keywords (``for/if/while...``).
6121
6122     .. code-block:: c++
6123
6124        void f() {
6125          if (true) {
6126            f();
6127          }
6128        }
6129
6130   * ``SBPO_ControlStatementsExceptControlMacros`` (in configuration: ``ControlStatementsExceptControlMacros``)
6131     Same as ``SBPO_ControlStatements`` except this option doesn't apply to
6132     ForEach and If macros. This is useful in projects where ForEach/If
6133     macros are treated as function calls instead of control statements.
6134     ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
6135     backward compatibility.
6136
6137     .. code-block:: c++
6138
6139        void f() {
6140          Q_FOREACH(...) {
6141            f();
6142          }
6143        }
6144
6145   * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``)
6146     Put a space before opening parentheses only if the parentheses are not
6147     empty.
6148
6149     .. code-block:: c++
6150
6151       void() {
6152         if (true) {
6153           f();
6154           g (x, y, z);
6155         }
6156       }
6157
6158   * ``SBPO_Always`` (in configuration: ``Always``)
6159     Always put a space before opening parentheses, except when it's
6160     prohibited by the syntax rules (in function-like macro definitions) or
6161     when determined by other style rules (after unary operators, opening
6162     parentheses, etc.)
6163
6164     .. code-block:: c++
6165
6166        void f () {
6167          if (true) {
6168            f ();
6169          }
6170        }
6171
6172   * ``SBPO_Custom`` (in configuration: ``Custom``)
6173     Configure each individual space before parentheses in
6174     ``SpaceBeforeParensOptions``.
6175
6176
6177
6178 .. _SpaceBeforeParensOptions:
6179
6180 **SpaceBeforeParensOptions** (``SpaceBeforeParensCustom``) :versionbadge:`clang-format 14` :ref:`¶ <SpaceBeforeParensOptions>`
6181   Control of individual space before parentheses.
6182
6183   If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify
6184   how each individual space before parentheses case should be handled.
6185   Otherwise, this is ignored.
6186
6187   .. code-block:: yaml
6188
6189     # Example of usage:
6190     SpaceBeforeParens: Custom
6191     SpaceBeforeParensOptions:
6192       AfterControlStatements: true
6193       AfterFunctionDefinitionName: true
6194
6195   Nested configuration flags:
6196
6197   Precise control over the spacing before parentheses.
6198
6199   .. code-block:: c++
6200
6201     # Should be declared this way:
6202     SpaceBeforeParens: Custom
6203     SpaceBeforeParensOptions:
6204       AfterControlStatements: true
6205       AfterFunctionDefinitionName: true
6206
6207   * ``bool AfterControlStatements`` If ``true``, put space between control statement keywords
6208     (for/if/while...) and opening parentheses.
6209
6210     .. code-block:: c++
6211
6212        true:                                  false:
6213        if (...) {}                     vs.    if(...) {}
6214
6215   * ``bool AfterForeachMacros`` If ``true``, put space between foreach macros and opening parentheses.
6216
6217     .. code-block:: c++
6218
6219        true:                                  false:
6220        FOREACH (...)                   vs.    FOREACH(...)
6221          <loop-body>                            <loop-body>
6222
6223   * ``bool AfterFunctionDeclarationName`` If ``true``, put a space between function declaration name and opening
6224     parentheses.
6225
6226     .. code-block:: c++
6227
6228        true:                                  false:
6229        void f ();                      vs.    void f();
6230
6231   * ``bool AfterFunctionDefinitionName`` If ``true``, put a space between function definition name and opening
6232     parentheses.
6233
6234     .. code-block:: c++
6235
6236        true:                                  false:
6237        void f () {}                    vs.    void f() {}
6238
6239   * ``bool AfterIfMacros`` If ``true``, put space between if macros and opening parentheses.
6240
6241     .. code-block:: c++
6242
6243        true:                                  false:
6244        IF (...)                        vs.    IF(...)
6245          <conditional-body>                     <conditional-body>
6246
6247   * ``bool AfterOverloadedOperator`` If ``true``, put a space between operator overloading and opening
6248     parentheses.
6249
6250     .. code-block:: c++
6251
6252        true:                                  false:
6253        void operator++ (int a);        vs.    void operator++(int a);
6254        object.operator++ (10);                object.operator++(10);
6255
6256   * ``bool AfterPlacementOperator`` If ``true``, put a space between operator ``new``/``delete`` and opening
6257     parenthesis.
6258
6259     .. code-block:: c++
6260
6261        true:                                  false:
6262        new (buf) T;                    vs.    new(buf) T;
6263        delete (buf) T;                        delete(buf) T;
6264
6265   * ``bool AfterRequiresInClause`` If ``true``, put space between requires keyword in a requires clause and
6266     opening parentheses, if there is one.
6267
6268     .. code-block:: c++
6269
6270        true:                                  false:
6271        template<typename T>            vs.    template<typename T>
6272        requires (A<T> && B<T>)                requires(A<T> && B<T>)
6273        ...                                    ...
6274
6275   * ``bool AfterRequiresInExpression`` If ``true``, put space between requires keyword in a requires expression
6276     and opening parentheses.
6277
6278     .. code-block:: c++
6279
6280        true:                                  false:
6281        template<typename T>            vs.    template<typename T>
6282        concept C = requires (T t) {           concept C = requires(T t) {
6283                      ...                                    ...
6284                    }                                      }
6285
6286   * ``bool BeforeNonEmptyParentheses`` If ``true``, put a space before opening parentheses only if the
6287     parentheses are not empty.
6288
6289     .. code-block:: c++
6290
6291        true:                                  false:
6292        void f (int a);                 vs.    void f();
6293        f (a);                                 f();
6294
6295
6296 .. _SpaceBeforeRangeBasedForLoopColon:
6297
6298 **SpaceBeforeRangeBasedForLoopColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeRangeBasedForLoopColon>`
6299   If ``false``, spaces will be removed before range-based for loop
6300   colon.
6301
6302   .. code-block:: c++
6303
6304      true:                                  false:
6305      for (auto v : values) {}       vs.     for(auto v: values) {}
6306
6307 .. _SpaceBeforeSquareBrackets:
6308
6309 **SpaceBeforeSquareBrackets** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceBeforeSquareBrackets>`
6310   If ``true``, spaces will be before  ``[``.
6311   Lambdas will not be affected. Only the first ``[`` will get a space added.
6312
6313   .. code-block:: c++
6314
6315      true:                                  false:
6316      int a [5];                    vs.      int a[5];
6317      int a [5][5];                 vs.      int a[5][5];
6318
6319 .. _SpaceInEmptyBlock:
6320
6321 **SpaceInEmptyBlock** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceInEmptyBlock>`
6322   If ``true``, spaces will be inserted into ``{}``.
6323
6324   .. code-block:: c++
6325
6326      true:                                false:
6327      void f() { }                   vs.   void f() {}
6328      while (true) { }                     while (true) {}
6329
6330 .. _SpaceInEmptyParentheses:
6331
6332 **SpaceInEmptyParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceInEmptyParentheses>`
6333   If ``true``, spaces may be inserted into ``()``.
6334   This option is **deprecated**. See ``InEmptyParentheses`` of
6335   ``SpacesInParensOptions``.
6336
6337 .. _SpacesBeforeTrailingComments:
6338
6339 **SpacesBeforeTrailingComments** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesBeforeTrailingComments>`
6340   The number of spaces before trailing line comments
6341   (``//`` - comments).
6342
6343   This does not affect trailing block comments (``/*`` - comments) as those
6344   commonly have different usage patterns and a number of special cases.  In
6345   the case of Verilog, it doesn't affect a comment right after the opening
6346   parenthesis in the port or parameter list in a module header, because it
6347   is probably for the port on the following line instead of the parenthesis
6348   it follows.
6349
6350   .. code-block:: c++
6351
6352      SpacesBeforeTrailingComments: 3
6353      void f() {
6354        if (true) {   // foo1
6355          f();        // bar
6356        }             // foo
6357      }
6358
6359 .. _SpacesInAngles:
6360
6361 **SpacesInAngles** (``SpacesInAnglesStyle``) :versionbadge:`clang-format 3.4` :ref:`¶ <SpacesInAngles>`
6362   The SpacesInAnglesStyle to use for template argument lists.
6363
6364   Possible values:
6365
6366   * ``SIAS_Never`` (in configuration: ``Never``)
6367     Remove spaces after ``<`` and before ``>``.
6368
6369     .. code-block:: c++
6370
6371        static_cast<int>(arg);
6372        std::function<void(int)> fct;
6373
6374   * ``SIAS_Always`` (in configuration: ``Always``)
6375     Add spaces after ``<`` and before ``>``.
6376
6377     .. code-block:: c++
6378
6379        static_cast< int >(arg);
6380        std::function< void(int) > fct;
6381
6382   * ``SIAS_Leave`` (in configuration: ``Leave``)
6383     Keep a single space after ``<`` and before ``>`` if any spaces were
6384     present. Option ``Standard: Cpp03`` takes precedence.
6385
6386
6387
6388 .. _SpacesInCStyleCastParentheses:
6389
6390 **SpacesInCStyleCastParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInCStyleCastParentheses>`
6391   If ``true``, spaces may be inserted into C style casts.
6392   This option is **deprecated**. See ``InCStyleCasts`` of
6393   ``SpacesInParensOptions``.
6394
6395 .. _SpacesInConditionalStatement:
6396
6397 **SpacesInConditionalStatement** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpacesInConditionalStatement>`
6398   If ``true``, spaces will be inserted around if/for/switch/while
6399   conditions.
6400   This option is **deprecated**. See ``InConditionalStatements`` of
6401   ``SpacesInParensOptions``.
6402
6403 .. _SpacesInContainerLiterals:
6404
6405 **SpacesInContainerLiterals** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInContainerLiterals>`
6406   If ``true``, spaces are inserted inside container literals (e.g.  ObjC and
6407   Javascript array and dict literals). For JSON, use
6408   ``SpaceBeforeJsonColon`` instead.
6409
6410   .. code-block:: js
6411
6412      true:                                  false:
6413      var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
6414      f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});
6415
6416 .. _SpacesInLineCommentPrefix:
6417
6418 **SpacesInLineCommentPrefix** (``SpacesInLineComment``) :versionbadge:`clang-format 13` :ref:`¶ <SpacesInLineCommentPrefix>`
6419   How many spaces are allowed at the start of a line comment. To disable the
6420   maximum set it to ``-1``, apart from that the maximum takes precedence
6421   over the minimum.
6422
6423   .. code-block:: c++
6424
6425     Minimum = 1
6426     Maximum = -1
6427     // One space is forced
6428
6429     //  but more spaces are possible
6430
6431     Minimum = 0
6432     Maximum = 0
6433     //Forces to start every comment directly after the slashes
6434
6435   Note that in line comment sections the relative indent of the subsequent
6436   lines is kept, that means the following:
6437
6438   .. code-block:: c++
6439
6440     before:                                   after:
6441     Minimum: 1
6442     //if (b) {                                // if (b) {
6443     //  return true;                          //   return true;
6444     //}                                       // }
6445
6446     Maximum: 0
6447     /// List:                                 ///List:
6448     ///  - Foo                                /// - Foo
6449     ///    - Bar                              ///   - Bar
6450
6451   This option has only effect if ``ReflowComments`` is set to ``true``.
6452
6453   Nested configuration flags:
6454
6455   Control of spaces within a single line comment.
6456
6457   * ``unsigned Minimum`` The minimum number of spaces at the start of the comment.
6458
6459   * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
6460
6461
6462 .. _SpacesInParens:
6463
6464 **SpacesInParens** (``SpacesInParensStyle``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParens>`
6465   Defines in which cases spaces will be inserted after ``(`` and before
6466   ``)``.
6467
6468   Possible values:
6469
6470   * ``SIPO_Never`` (in configuration: ``Never``)
6471     Never put a space in parentheses.
6472
6473     .. code-block:: c++
6474
6475        void f() {
6476          if(true) {
6477            f();
6478          }
6479        }
6480
6481   * ``SIPO_Custom`` (in configuration: ``Custom``)
6482     Configure each individual space in parentheses in
6483     `SpacesInParensOptions`.
6484
6485
6486
6487 .. _SpacesInParensOptions:
6488
6489 **SpacesInParensOptions** (``SpacesInParensCustom``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParensOptions>`
6490   Control of individual spaces in parentheses.
6491
6492   If ``SpacesInParens`` is set to ``Custom``, use this to specify
6493   how each individual space in parentheses case should be handled.
6494   Otherwise, this is ignored.
6495
6496   .. code-block:: yaml
6497
6498     # Example of usage:
6499     SpacesInParens: Custom
6500     SpacesInParensOptions:
6501       ExceptDoubleParentheses: false
6502       InConditionalStatements: true
6503       InEmptyParentheses: true
6504
6505   Nested configuration flags:
6506
6507   Precise control over the spacing in parentheses.
6508
6509   .. code-block:: c++
6510
6511     # Should be declared this way:
6512     SpacesInParens: Custom
6513     SpacesInParensOptions:
6514       ExceptDoubleParentheses: false
6515       InConditionalStatements: true
6516       Other: true
6517
6518   * ``bool ExceptDoubleParentheses`` Override any of the following options to prevent addition of space
6519     when both opening and closing parentheses use multiple parentheses.
6520
6521     .. code-block:: c++
6522
6523       true:
6524       __attribute__(( noreturn ))
6525       __decltype__(( x ))
6526       if (( a = b ))
6527      false:
6528        Uses the applicable option.
6529
6530   * ``bool InConditionalStatements`` Put a space in parentheses only inside conditional statements
6531     (``for/if/while/switch...``).
6532
6533     .. code-block:: c++
6534
6535        true:                                  false:
6536        if ( a )  { ... }              vs.     if (a) { ... }
6537        while ( i < 5 )  { ... }               while (i < 5) { ... }
6538
6539   * ``bool InCStyleCasts`` Put a space in C style casts.
6540
6541     .. code-block:: c++
6542
6543       true:                                  false:
6544       x = ( int32 )y                  vs.    x = (int32)y
6545       y = (( int (*)(int) )foo)(x);          y = ((int (*)(int))foo)(x);
6546
6547   * ``bool InEmptyParentheses`` Insert a space in empty parentheses, i.e. ``()``.
6548
6549     .. code-block:: c++
6550
6551        true:                                false:
6552        void f( ) {                    vs.   void f() {
6553          int x[] = {foo( ), bar( )};          int x[] = {foo(), bar()};
6554          if (true) {                          if (true) {
6555            f( );                                f();
6556          }                                    }
6557        }                                    }
6558
6559   * ``bool Other`` Put a space in parentheses not covered by preceding options.
6560
6561     .. code-block:: c++
6562
6563       true:                                 false:
6564       t f( Deleted & ) & = delete;    vs.   t f(Deleted &) & = delete;
6565
6566
6567 .. _SpacesInParentheses:
6568
6569 **SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInParentheses>`
6570   If ``true``, spaces will be inserted after ``(`` and before ``)``.
6571   This option is **deprecated**. The previous behavior is preserved by using
6572   ``SpacesInParens`` with ``Custom`` and by setting all
6573   ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and
6574   ``InEmptyParentheses``.
6575
6576 .. _SpacesInSquareBrackets:
6577
6578 **SpacesInSquareBrackets** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInSquareBrackets>`
6579   If ``true``, spaces will be inserted after ``[`` and before ``]``.
6580   Lambdas without arguments or unspecified size array declarations will not
6581   be affected.
6582
6583   .. code-block:: c++
6584
6585      true:                                  false:
6586      int a[ 5 ];                    vs.     int a[5];
6587      std::unique_ptr<int[]> foo() {} // Won't be affected
6588
6589 .. _Standard:
6590
6591 **Standard** (``LanguageStandard``) :versionbadge:`clang-format 3.7` :ref:`¶ <Standard>`
6592   Parse and format C++ constructs compatible with this standard.
6593
6594   .. code-block:: c++
6595
6596      c++03:                                 latest:
6597      vector<set<int> > x;           vs.     vector<set<int>> x;
6598
6599   Possible values:
6600
6601   * ``LS_Cpp03`` (in configuration: ``c++03``)
6602     Parse and format as C++03.
6603     ``Cpp03`` is a deprecated alias for ``c++03``
6604
6605   * ``LS_Cpp11`` (in configuration: ``c++11``)
6606     Parse and format as C++11.
6607
6608   * ``LS_Cpp14`` (in configuration: ``c++14``)
6609     Parse and format as C++14.
6610
6611   * ``LS_Cpp17`` (in configuration: ``c++17``)
6612     Parse and format as C++17.
6613
6614   * ``LS_Cpp20`` (in configuration: ``c++20``)
6615     Parse and format as C++20.
6616
6617   * ``LS_Latest`` (in configuration: ``Latest``)
6618     Parse and format using the latest supported language version.
6619     ``Cpp11`` is a deprecated alias for ``Latest``
6620
6621   * ``LS_Auto`` (in configuration: ``Auto``)
6622     Automatic detection based on the input.
6623
6624
6625
6626 .. _StatementAttributeLikeMacros:
6627
6628 **StatementAttributeLikeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <StatementAttributeLikeMacros>`
6629   Macros which are ignored in front of a statement, as if they were an
6630   attribute. So that they are not parsed as identifier, for example for Qts
6631   emit.
6632
6633   .. code-block:: c++
6634
6635     AlignConsecutiveDeclarations: true
6636     StatementAttributeLikeMacros: []
6637     unsigned char data = 'x';
6638     emit          signal(data); // This is parsed as variable declaration.
6639
6640     AlignConsecutiveDeclarations: true
6641     StatementAttributeLikeMacros: [emit]
6642     unsigned char data = 'x';
6643     emit signal(data); // Now it's fine again.
6644
6645 .. _StatementMacros:
6646
6647 **StatementMacros** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <StatementMacros>`
6648   A vector of macros that should be interpreted as complete
6649   statements.
6650
6651   Typical macros are expressions, and require a semi-colon to be
6652   added; sometimes this is not the case, and this allows to make
6653   clang-format aware of such cases.
6654
6655   For example: Q_UNUSED
6656
6657 .. _TabWidth:
6658
6659 **TabWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <TabWidth>`
6660   The number of columns used for tab stops.
6661
6662 .. _TableGenBreakInsideDAGArg:
6663
6664 **TableGenBreakInsideDAGArg** (``DAGArgStyle``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakInsideDAGArg>`
6665   The styles of the line break inside the DAGArg in TableGen.
6666
6667   Possible values:
6668
6669   * ``DAS_DontBreak`` (in configuration: ``DontBreak``)
6670     Never break inside DAGArg.
6671
6672     .. code-block:: c++
6673
6674       let DAGArgIns = (ins i32:$src1, i32:$src2);
6675
6676   * ``DAS_BreakElements`` (in configuration: ``BreakElements``)
6677     Break inside DAGArg after each list element but for the last.
6678     This aligns to the first element.
6679
6680     .. code-block:: c++
6681
6682       let DAGArgIns = (ins i32:$src1,
6683                            i32:$src2);
6684
6685   * ``DAS_BreakAll`` (in configuration: ``BreakAll``)
6686     Break inside DAGArg after the operator and the all elements.
6687
6688     .. code-block:: c++
6689
6690       let DAGArgIns = (ins
6691           i32:$src1,
6692           i32:$src2
6693       );
6694
6695
6696
6697 .. _TableGenBreakingDAGArgOperators:
6698
6699 **TableGenBreakingDAGArgOperators** (``List of Strings``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakingDAGArgOperators>`
6700   Works only when TableGenBreakInsideDAGArg is not DontBreak.
6701   The string list needs to consist of identifiers in TableGen.
6702   If any identifier is specified, this limits the line breaks by
6703   TableGenBreakInsideDAGArg option only on DAGArg values beginning with
6704   the specified identifiers.
6705
6706   For example the configuration,
6707
6708   .. code-block:: yaml
6709
6710     TableGenBreakInsideDAGArg: BreakAll
6711     TableGenBreakingDAGArgOperators: [ins, outs]
6712
6713   makes the line break only occurs inside DAGArgs beginning with the
6714   specified identifiers ``ins`` and ``outs``.
6715
6716
6717   .. code-block:: c++
6718
6719     let DAGArgIns = (ins
6720         i32:$src1,
6721         i32:$src2
6722     );
6723     let DAGArgOtherID = (other i32:$other1, i32:$other2);
6724     let DAGArgBang = (!cast<SomeType>("Some") i32:$src1, i32:$src2)
6725
6726 .. _TemplateNames:
6727
6728 **TemplateNames** (``List of Strings``) :versionbadge:`clang-format 20` :ref:`¶ <TemplateNames>`
6729   A vector of non-keyword identifiers that should be interpreted as
6730   template names.
6731
6732   A ``<`` after a template name is annotated as a template opener instead of
6733   a binary operator.
6734
6735 .. _TypeNames:
6736
6737 **TypeNames** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <TypeNames>`
6738   A vector of non-keyword identifiers that should be interpreted as type
6739   names.
6740
6741   A ``*``, ``&``, or ``&&`` between a type name and another non-keyword
6742   identifier is annotated as a pointer or reference token instead of a
6743   binary operator.
6744
6745 .. _TypenameMacros:
6746
6747 **TypenameMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <TypenameMacros>`
6748   A vector of macros that should be interpreted as type declarations
6749   instead of as function calls.
6750
6751   These are expected to be macros of the form:
6752
6753   .. code-block:: c++
6754
6755     STACK_OF(...)
6756
6757   In the .clang-format configuration file, this can be configured like:
6758
6759   .. code-block:: yaml
6760
6761     TypenameMacros: [STACK_OF, LIST]
6762
6763   For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
6764
6765 .. _UseCRLF:
6766
6767 **UseCRLF** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <UseCRLF>`
6768   This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``.
6769
6770 .. _UseTab:
6771
6772 **UseTab** (``UseTabStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <UseTab>`
6773   The way to use tab characters in the resulting file.
6774
6775   Possible values:
6776
6777   * ``UT_Never`` (in configuration: ``Never``)
6778     Never use tab.
6779
6780   * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
6781     Use tabs only for indentation.
6782
6783   * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
6784     Fill all leading whitespace with tabs, and use spaces for alignment that
6785     appears within a line (e.g. consecutive assignments and declarations).
6786
6787   * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
6788     Use tabs for line continuation and indentation, and spaces for
6789     alignment.
6790
6791   * ``UT_Always`` (in configuration: ``Always``)
6792     Use tabs whenever we need to fill whitespace that spans at least from
6793     one tab stop to the next one.
6794
6795
6796
6797 .. _VerilogBreakBetweenInstancePorts:
6798
6799 **VerilogBreakBetweenInstancePorts** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <VerilogBreakBetweenInstancePorts>`
6800   For Verilog, put each port on its own line in module instantiations.
6801
6802   .. code-block:: c++
6803
6804      true:
6805      ffnand ff1(.q(),
6806                 .qbar(out1),
6807                 .clear(in1),
6808                 .preset(in2));
6809
6810      false:
6811      ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2));
6812
6813 .. _WhitespaceSensitiveMacros:
6814
6815 **WhitespaceSensitiveMacros** (``List of Strings``) :versionbadge:`clang-format 11` :ref:`¶ <WhitespaceSensitiveMacros>`
6816   A vector of macros which are whitespace-sensitive and should not
6817   be touched.
6818
6819   These are expected to be macros of the form:
6820
6821   .. code-block:: c++
6822
6823     STRINGIZE(...)
6824
6825   In the .clang-format configuration file, this can be configured like:
6826
6827   .. code-block:: yaml
6828
6829     WhitespaceSensitiveMacros: [STRINGIZE, PP_STRINGIZE]
6830
6831   For example: BOOST_PP_STRINGIZE
6832
6833 .. END_FORMAT_STYLE_OPTIONS
6834
6835 Adding additional style options
6836 ===============================
6837
6838 Each additional style option adds costs to the clang-format project. Some of
6839 these costs affect the clang-format development itself, as we need to make
6840 sure that any given combination of options work and that new features don't
6841 break any of the existing options in any way. There are also costs for end users
6842 as options become less discoverable and people have to think about and make a
6843 decision on options they don't really care about.
6844
6845 The goal of the clang-format project is more on the side of supporting a
6846 limited set of styles really well as opposed to supporting every single style
6847 used by a codebase somewhere in the wild. Of course, we do want to support all
6848 major projects and thus have established the following bar for adding style
6849 options. Each new style option must:
6850
6851   * be used in a project of significant size (have dozens of contributors)
6852   * have a publicly accessible style guide
6853   * have a person willing to contribute and maintain patches
6854
6855 Examples
6856 ========
6857
6858 A style similar to the `Linux Kernel style
6859 <https://www.kernel.org/doc/html/latest/process/coding-style.html>`_:
6860
6861 .. code-block:: yaml
6862
6863   BasedOnStyle: LLVM
6864   IndentWidth: 8
6865   UseTab: Always
6866   BreakBeforeBraces: Linux
6867   AllowShortIfStatementsOnASingleLine: false
6868   IndentCaseLabels: false
6869
6870 The result is (imagine that tabs are used for indentation here):
6871
6872 .. code-block:: c++
6873
6874   void test()
6875   {
6876           switch (x) {
6877           case 0:
6878           case 1:
6879                   do_something();
6880                   break;
6881           case 2:
6882                   do_something_else();
6883                   break;
6884           default:
6885                   break;
6886           }
6887           if (condition)
6888                   do_something_completely_different();
6889
6890           if (x == y) {
6891                   q();
6892           } else if (x > y) {
6893                   w();
6894           } else {
6895                   r();
6896           }
6897   }
6898
6899 A style similar to the default Visual Studio formatting style:
6900
6901 .. code-block:: yaml
6902
6903   UseTab: Never
6904   IndentWidth: 4
6905   BreakBeforeBraces: Allman
6906   AllowShortIfStatementsOnASingleLine: false
6907   IndentCaseLabels: false
6908   ColumnLimit: 0
6909
6910 The result is:
6911
6912 .. code-block:: c++
6913
6914   void test()
6915   {
6916       switch (suffix)
6917       {
6918       case 0:
6919       case 1:
6920           do_something();
6921           break;
6922       case 2:
6923           do_something_else();
6924           break;
6925       default:
6926           break;
6927       }
6928       if (condition)
6929           do_something_completely_different();
6930
6931       if (x == y)
6932       {
6933           q();
6934       }
6935       else if (x > y)
6936       {
6937           w();
6938       }
6939       else
6940       {
6941           r();
6942       }
6943   }