clang/docs/ClangFormatStyleOptions.rst

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