clang/docs/ClangFormatStyleOptions.rst

   1 ==========================
   2 Clang-Format Style Options
   3 ==========================
   4
   5 :doc:`ClangFormatStyleOptions` describes configurable formatting style options
   6 supported by :doc:`LibFormat` and :doc:`ClangFormat`.
   7
   8 When using :program:`clang-format` command line utility or
   9 ``clang::format::reformat(...)`` functions from code, one can either use one of
  10 the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or
  11 create a custom style by configuring specific style options.
  12
  13
  14 Configuring Style with clang-format
  15 ===================================
  16
  17 :program:`clang-format` supports two ways to provide custom style options:
  18 directly specify style configuration in the ``-style=`` command line option or
  19 use ``-style=file`` and put style configuration in the ``.clang-format`` or
  20 ``_clang-format`` file in the project directory.
  21
  22 When using ``-style=file``, :program:`clang-format` for each input file will
  23 try to find the ``.clang-format`` file located in the closest parent directory
  24 of the input file. When the standard input is used, the search is started from
  25 the current directory.
  26
  27 The ``.clang-format`` file uses YAML format:
  28
  29 .. code-block:: yaml
  30
  31   key1: value1
  32   key2: value2
  33   # A comment.
  34   ...
  35
  36 The configuration file can consist of several sections each having different
  37 ``Language:`` parameter denoting the programming language this section of the
  38 configuration is targeted at. See the description of the **Language** option
  39 below for the list of supported languages. The first section may have no
  40 language set, it will set the default style options for all lanugages.
  41 Configuration sections for specific language will override options set in the
  42 default section.
  43
  44 When :program:`clang-format` formats a file, it auto-detects the language using
  45 the file name. When formatting standard input or a file that doesn't have the
  46 extension corresponding to its language, ``-assume-filename=`` option can be
  47 used to override the file name :program:`clang-format` uses to detect the
  48 language.
  49
  50 An example of a configuration file for multiple languages:
  51
  52 .. code-block:: yaml
  53
  54   ---
  55   # We'll use defaults from the LLVM style, but with 4 columns indentation.
  56   BasedOnStyle: LLVM
  57   IndentWidth: 4
  58   ---
  59   Language: Cpp
  60   # Force pointers to the type for C++.
  61   DerivePointerAlignment: false
  62   PointerAlignment: Left
  63   ---
  64   Language: JavaScript
  65   # Use 100 columns for JS.
  66   ColumnLimit: 100
  67   ---
  68   Language: Proto
  69   # Don't format .proto files.
  70   DisableFormat: true
  71   ---
  72   Language: CSharp
  73   # Use 100 columns for C#.
  74   ColumnLimit: 100
  75   ...
  76
  77 An easy way to get a valid ``.clang-format`` file containing all configuration
  78 options of a certain predefined style is:
  79
  80 .. code-block:: console
  81
  82   clang-format -style=llvm -dump-config > .clang-format
  83
  84 When specifying configuration in the ``-style=`` option, the same configuration
  85 is applied for all input files. The format of the configuration is:
  86
  87 .. code-block:: console
  88
  89   -style='{key1: value1, key2: value2, ...}'
  90
  91
  92 Disabling Formatting on a Piece of Code
  93 =======================================
  94
  95 Clang-format understands also special comments that switch formatting in a
  96 delimited range. The code between a comment ``// clang-format off`` or
  97 ``/* clang-format off */`` up to a comment ``// clang-format on`` or
  98 ``/* clang-format on */`` will not be formatted. The comments themselves
  99 will be formatted (aligned) normally.
 100
 101 .. code-block:: c++
 102
 103   int formatted_code;
 104   // clang-format off
 105       void    unformatted_code  ;
 106   // clang-format on
 107   void formatted_code_again;
 108
 109
 110 Configuring Style in Code
 111 =========================
 112
 113 When using ``clang::format::reformat(...)`` functions, the format is specified
 114 by supplying the `clang::format::FormatStyle
 115 <https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
 116 structure.
 117
 118
 119 Configurable Format Style Options
 120 =================================
 121
 122 This section lists the supported style options. Value type is specified for
 123 each option. For enumeration types possible values are specified both as a C++
 124 enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
 125 the configuration (without a prefix: ``Auto``).
 126
 127
 128 **BasedOnStyle** (``string``)
 129   The style used for all options not specifically set in the configuration.
 130
 131   This option is supported only in the :program:`clang-format` configuration
 132   (both within ``-style='{...}'`` and the ``.clang-format`` file).
 133
 134   Possible values:
 135
 136   * ``LLVM``
 137     A style complying with the `LLVM coding standards
 138     <https://llvm.org/docs/CodingStandards.html>`_
 139   * ``Google``
 140     A style complying with `Google's C++ style guide
 141     <https://google.github.io/styleguide/cppguide.html>`_
 142   * ``Chromium``
 143     A style complying with `Chromium's style guide
 144     <https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md>`_
 145   * ``Mozilla``
 146     A style complying with `Mozilla's style guide
 147     <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
 148   * ``WebKit``
 149     A style complying with `WebKit's style guide
 150     <https://www.webkit.org/coding/coding-style.html>`_
 151   * ``Microsoft``
 152     A style complying with `Microsoft's style guide
 153     <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_
 154   * ``GNU``
 155     A style complying with the `GNU coding standards
 156     <https://www.gnu.org/prep/standards/standards.html>`_
 157
 158 .. START_FORMAT_STYLE_OPTIONS
 159
 160 **AccessModifierOffset** (``int``)
 161   The extra indent or outdent of access modifiers, e.g. ``public:``.
 162
 163 **AlignAfterOpenBracket** (``BracketAlignmentStyle``)
 164   If ``true``, horizontally aligns arguments after an open bracket.
 165
 166   This applies to round brackets (parentheses), angle brackets and square
 167   brackets.
 168
 169   Possible values:
 170
 171   * ``BAS_Align`` (in configuration: ``Align``)
 172     Align parameters on the open bracket, e.g.:
 173
 174     .. code-block:: c++
 175
 176       someLongFunction(argument1,
 177                        argument2);
 178
 179   * ``BAS_DontAlign`` (in configuration: ``DontAlign``)
 180     Don't align, instead use ``ContinuationIndentWidth``, e.g.:
 181
 182     .. code-block:: c++
 183
 184       someLongFunction(argument1,
 185           argument2);
 186
 187   * ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
 188     Always break after an open bracket, if the parameters don't fit
 189     on a single line, e.g.:
 190
 191     .. code-block:: c++
 192
 193       someLongFunction(
 194           argument1, argument2);
 195
 196
 197
 198 **AlignConsecutiveAssignments** (``bool``)
 199   If ``true``, aligns consecutive assignments.
 200
 201   This will align the assignment operators of consecutive lines. This
 202   will result in formattings like
 203
 204   .. code-block:: c++
 205
 206     int aaaa = 12;
 207     int b    = 23;
 208     int ccc  = 23;
 209
 210 **AlignConsecutiveBitFields** (``bool``)
 211   If ``true``, aligns consecutive bitfield members.
 212
 213   This will align the bitfield separators of consecutive lines. This
 214   will result in formattings like
 215
 216   .. code-block:: c++
 217
 218     int aaaa : 1;
 219     int b    : 12;
 220     int ccc  : 8;
 221
 222 **AlignConsecutiveDeclarations** (``bool``)
 223   If ``true``, aligns consecutive declarations.
 224
 225   This will align the declaration names of consecutive lines. This
 226   will result in formattings like
 227
 228   .. code-block:: c++
 229
 230     int         aaaa = 12;
 231     float       b = 23;
 232     std::string ccc = 23;
 233
 234 **AlignConsecutiveMacros** (``bool``)
 235   If ``true``, aligns consecutive C/C++ preprocessor macros.
 236
 237   This will align C/C++ preprocessor macros of consecutive lines.
 238   Will result in formattings like
 239
 240   .. code-block:: c++
 241
 242     #define SHORT_NAME       42
 243     #define LONGER_NAME      0x007f
 244     #define EVEN_LONGER_NAME (2)
 245     #define foo(x)           (x * x)
 246     #define bar(y, z)        (y + z)
 247
 248 **AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``)
 249   Options for aligning backslashes in escaped newlines.
 250
 251   Possible values:
 252
 253   * ``ENAS_DontAlign`` (in configuration: ``DontAlign``)
 254     Don't align escaped newlines.
 255
 256     .. code-block:: c++
 257
 258       #define A \
 259         int aaaa; \
 260         int b; \
 261         int dddddddddd;
 262
 263   * ``ENAS_Left`` (in configuration: ``Left``)
 264     Align escaped newlines as far left as possible.
 265
 266     .. code-block:: c++
 267
 268       true:
 269       #define A   \
 270         int aaaa; \
 271         int b;    \
 272         int dddddddddd;
 273
 274       false:
 275
 276   * ``ENAS_Right`` (in configuration: ``Right``)
 277     Align escaped newlines in the right-most column.
 278
 279     .. code-block:: c++
 280
 281       #define A                                                                      \
 282         int aaaa;                                                                    \
 283         int b;                                                                       \
 284         int dddddddddd;
 285
 286
 287
 288 **AlignOperands** (``OperandAlignmentStyle``)
 289   If ``true``, horizontally align operands of binary and ternary
 290   expressions.
 291
 292   Possible values:
 293
 294   * ``OAS_DontAlign`` (in configuration: ``DontAlign``)
 295     Do not align operands of binary and ternary expressions.
 296     The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
 297     the start of the line.
 298
 299   * ``OAS_Align`` (in configuration: ``Align``)
 300     Horizontally align operands of binary and ternary expressions.
 301
 302     Specifically, this aligns operands of a single expression that needs
 303     to be split over multiple lines, e.g.:
 304
 305     .. code-block:: c++
 306
 307       int aaa = bbbbbbbbbbbbbbb +
 308                 ccccccccccccccc;
 309
 310     When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
 311     aligned with the operand on the first line.
 312
 313     .. code-block:: c++
 314
 315       int aaa = bbbbbbbbbbbbbbb
 316                 + ccccccccccccccc;
 317
 318   * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``)
 319     Horizontally align operands of binary and ternary expressions.
 320
 321     This is similar to ``AO_Align``, except when
 322     ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
 323     that the wrapped operand is aligned with the operand on the first line.
 324
 325     .. code-block:: c++
 326
 327       int aaa = bbbbbbbbbbbbbbb
 328               + ccccccccccccccc;
 329
 330
 331
 332 **AlignTrailingComments** (``bool``)
 333   If ``true``, aligns trailing comments.
 334
 335   .. code-block:: c++
 336
 337     true:                                   false:
 338     int a;     // My comment a      vs.     int a; // My comment a
 339     int b = 2; // comment  b                int b = 2; // comment about b
 340
 341 **AllowAllArgumentsOnNextLine** (``bool``)
 342   If a function call or braced initializer list doesn't fit on a
 343   line, allow putting all arguments onto the next line, even if
 344   ``BinPackArguments`` is ``false``.
 345
 346   .. code-block:: c++
 347
 348     true:
 349     callFunction(
 350         a, b, c, d);
 351
 352     false:
 353     callFunction(a,
 354                  b,
 355                  c,
 356                  d);
 357
 358 **AllowAllConstructorInitializersOnNextLine** (``bool``)
 359   If a constructor definition with a member initializer list doesn't
 360   fit on a single line, allow putting all member initializers onto the next
 361   line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true.
 362   Note that this parameter has no effect if
 363   ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false.
 364
 365   .. code-block:: c++
 366
 367     true:
 368     MyClass::MyClass() :
 369         member0(0), member1(2) {}
 370
 371     false:
 372     MyClass::MyClass() :
 373         member0(0),
 374         member1(2) {}
 375
 376 **AllowAllParametersOfDeclarationOnNextLine** (``bool``)
 377   If the function declaration doesn't fit on a line,
 378   allow putting all parameters of a function declaration onto
 379   the next line even if ``BinPackParameters`` is ``false``.
 380
 381   .. code-block:: c++
 382
 383     true:
 384     void myFunction(
 385         int a, int b, int c, int d, int e);
 386
 387     false:
 388     void myFunction(int a,
 389                     int b,
 390                     int c,
 391                     int d,
 392                     int e);
 393
 394 **AllowShortBlocksOnASingleLine** (``ShortBlockStyle``)
 395   Dependent on the value, ``while (true) { continue; }`` can be put on a
 396   single line.
 397
 398   Possible values:
 399
 400   * ``SBS_Never`` (in configuration: ``Never``)
 401     Never merge blocks into a single line.
 402
 403     .. code-block:: c++
 404
 405       while (true) {
 406       }
 407       while (true) {
 408         continue;
 409       }
 410
 411   * ``SBS_Empty`` (in configuration: ``Empty``)
 412     Only merge empty blocks.
 413
 414     .. code-block:: c++
 415
 416       while (true) {}
 417       while (true) {
 418         continue;
 419       }
 420
 421   * ``SBS_Always`` (in configuration: ``Always``)
 422     Always merge short blocks into a single line.
 423
 424     .. code-block:: c++
 425
 426       while (true) {}
 427       while (true) { continue; }
 428
 429
 430
 431 **AllowShortCaseLabelsOnASingleLine** (``bool``)
 432   If ``true``, short case labels will be contracted to a single line.
 433
 434   .. code-block:: c++
 435
 436     true:                                   false:
 437     switch (a) {                    vs.     switch (a) {
 438     case 1: x = 1; break;                   case 1:
 439     case 2: return;                           x = 1;
 440     }                                         break;
 441                                             case 2:
 442                                               return;
 443                                             }
 444
 445 **AllowShortEnumsOnASingleLine** (``bool``)
 446   Allow short enums on a single line.
 447
 448   .. code-block:: c++
 449
 450     true:
 451     enum { A, B } myEnum;
 452
 453     false:
 454     enum
 455     {
 456       A,
 457       B
 458     } myEnum;
 459
 460 **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
 461   Dependent on the value, ``int f() { return 0; }`` can be put on a
 462   single line.
 463
 464   Possible values:
 465
 466   * ``SFS_None`` (in configuration: ``None``)
 467     Never merge functions into a single line.
 468
 469   * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``)
 470     Only merge functions defined inside a class. Same as "inline",
 471     except it does not implies "empty": i.e. top level empty functions
 472     are not merged either.
 473
 474     .. code-block:: c++
 475
 476       class Foo {
 477         void f() { foo(); }
 478       };
 479       void f() {
 480         foo();
 481       }
 482       void f() {
 483       }
 484
 485   * ``SFS_Empty`` (in configuration: ``Empty``)
 486     Only merge empty functions.
 487
 488     .. code-block:: c++
 489
 490       void f() {}
 491       void f2() {
 492         bar2();
 493       }
 494
 495   * ``SFS_Inline`` (in configuration: ``Inline``)
 496     Only merge functions defined inside a class. Implies "empty".
 497
 498     .. code-block:: c++
 499
 500       class Foo {
 501         void f() { foo(); }
 502       };
 503       void f() {
 504         foo();
 505       }
 506       void f() {}
 507
 508   * ``SFS_All`` (in configuration: ``All``)
 509     Merge all functions fitting on a single line.
 510
 511     .. code-block:: c++
 512
 513       class Foo {
 514         void f() { foo(); }
 515       };
 516       void f() { bar(); }
 517
 518
 519
 520 **AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``)
 521   If ``true``, ``if (a) return;`` can be put on a single line.
 522
 523   Possible values:
 524
 525   * ``SIS_Never`` (in configuration: ``Never``)
 526     Never put short ifs on the same line.
 527
 528     .. code-block:: c++
 529
 530       if (a)
 531         return ;
 532       else {
 533         return;
 534       }
 535
 536   * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``)
 537     Without else put short ifs on the same line only if
 538     the else is not a compound statement.
 539
 540     .. code-block:: c++
 541
 542       if (a) return;
 543       else
 544         return;
 545
 546   * ``SIS_Always`` (in configuration: ``Always``)
 547     Always put short ifs on the same line if
 548     the else is not a compound statement or not.
 549
 550     .. code-block:: c++
 551
 552       if (a) return;
 553       else {
 554         return;
 555       }
 556
 557
 558
 559 **AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``)
 560   Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
 561   single line.
 562
 563   Possible values:
 564
 565   * ``SLS_None`` (in configuration: ``None``)
 566     Never merge lambdas into a single line.
 567
 568   * ``SLS_Empty`` (in configuration: ``Empty``)
 569     Only merge empty lambdas.
 570
 571     .. code-block:: c++
 572
 573       auto lambda = [](int a) {}
 574       auto lambda2 = [](int a) {
 575           return a;
 576       };
 577
 578   * ``SLS_Inline`` (in configuration: ``Inline``)
 579     Merge lambda into a single line if argument of a function.
 580
 581     .. code-block:: c++
 582
 583       auto lambda = [](int a) {
 584           return a;
 585       };
 586       sort(a.begin(), a.end(), ()[] { return x < y; })
 587
 588   * ``SLS_All`` (in configuration: ``All``)
 589     Merge all lambdas fitting on a single line.
 590
 591     .. code-block:: c++
 592
 593       auto lambda = [](int a) {}
 594       auto lambda2 = [](int a) { return a; };
 595
 596
 597
 598 **AllowShortLoopsOnASingleLine** (``bool``)
 599   If ``true``, ``while (true) continue;`` can be put on a single
 600   line.
 601
 602 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
 603   The function definition return type breaking style to use.  This
 604   option is **deprecated** and is retained for backwards compatibility.
 605
 606   Possible values:
 607
 608   * ``DRTBS_None`` (in configuration: ``None``)
 609     Break after return type automatically.
 610     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
 611
 612   * ``DRTBS_All`` (in configuration: ``All``)
 613     Always break after the return type.
 614
 615   * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
 616     Always break after the return types of top-level functions.
 617
 618
 619
 620 **AlwaysBreakAfterReturnType** (``ReturnTypeBreakingStyle``)
 621   The function declaration return type breaking style to use.
 622
 623   Possible values:
 624
 625   * ``RTBS_None`` (in configuration: ``None``)
 626     Break after return type automatically.
 627     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
 628
 629     .. code-block:: c++
 630
 631       class A {
 632         int f() { return 0; };
 633       };
 634       int f();
 635       int f() { return 1; }
 636
 637   * ``RTBS_All`` (in configuration: ``All``)
 638     Always break after the return type.
 639
 640     .. code-block:: c++
 641
 642       class A {
 643         int
 644         f() {
 645           return 0;
 646         };
 647       };
 648       int
 649       f();
 650       int
 651       f() {
 652         return 1;
 653       }
 654
 655   * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
 656     Always break after the return types of top-level functions.
 657
 658     .. code-block:: c++
 659
 660       class A {
 661         int f() { return 0; };
 662       };
 663       int
 664       f();
 665       int
 666       f() {
 667         return 1;
 668       }
 669
 670   * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
 671     Always break after the return type of function definitions.
 672
 673     .. code-block:: c++
 674
 675       class A {
 676         int
 677         f() {
 678           return 0;
 679         };
 680       };
 681       int f();
 682       int
 683       f() {
 684         return 1;
 685       }
 686
 687   * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
 688     Always break after the return type of top-level definitions.
 689
 690     .. code-block:: c++
 691
 692       class A {
 693         int f() { return 0; };
 694       };
 695       int f();
 696       int
 697       f() {
 698         return 1;
 699       }
 700
 701
 702
 703 **AlwaysBreakBeforeMultilineStrings** (``bool``)
 704   If ``true``, always break before multiline string literals.
 705
 706   This flag is mean to make cases where there are multiple multiline strings
 707   in a file look more consistent. Thus, it will only take effect if wrapping
 708   the string at that point leads to it being indented
 709   ``ContinuationIndentWidth`` spaces from the start of the line.
 710
 711   .. code-block:: c++
 712
 713      true:                                  false:
 714      aaaa =                         vs.     aaaa = "bbbb"
 715          "bbbb"                                    "cccc";
 716          "cccc";
 717
 718 **AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``)
 719   The template declaration breaking style to use.
 720
 721   Possible values:
 722
 723   * ``BTDS_No`` (in configuration: ``No``)
 724     Do not force break before declaration.
 725     ``PenaltyBreakTemplateDeclaration`` is taken into account.
 726
 727     .. code-block:: c++
 728
 729        template <typename T> T foo() {
 730        }
 731        template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
 732                                    int bbbbbbbbbbbbbbbbbbbbb) {
 733        }
 734
 735   * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
 736     Force break after template declaration only when the following
 737     declaration spans multiple lines.
 738
 739     .. code-block:: c++
 740
 741        template <typename T> T foo() {
 742        }
 743        template <typename T>
 744        T foo(int aaaaaaaaaaaaaaaaaaaaa,
 745              int bbbbbbbbbbbbbbbbbbbbb) {
 746        }
 747
 748   * ``BTDS_Yes`` (in configuration: ``Yes``)
 749     Always break after template declaration.
 750
 751     .. code-block:: c++
 752
 753        template <typename T>
 754        T foo() {
 755        }
 756        template <typename T>
 757        T foo(int aaaaaaaaaaaaaaaaaaaaa,
 758              int bbbbbbbbbbbbbbbbbbbbb) {
 759        }
 760
 761
 762
 763 **BinPackArguments** (``bool``)
 764   If ``false``, a function call's arguments will either be all on the
 765   same line or will have one line each.
 766
 767   .. code-block:: c++
 768
 769     true:
 770     void f() {
 771       f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
 772         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
 773     }
 774
 775     false:
 776     void f() {
 777       f(aaaaaaaaaaaaaaaaaaaa,
 778         aaaaaaaaaaaaaaaaaaaa,
 779         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
 780     }
 781
 782 **BinPackParameters** (``bool``)
 783   If ``false``, a function declaration's or function definition's
 784   parameters will either all be on the same line or will have one line each.
 785
 786   .. code-block:: c++
 787
 788     true:
 789     void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
 790            int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
 791
 792     false:
 793     void f(int aaaaaaaaaaaaaaaaaaaa,
 794            int aaaaaaaaaaaaaaaaaaaa,
 795            int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
 796
 797 **BraceWrapping** (``BraceWrappingFlags``)
 798   Control of individual brace wrapping cases.
 799
 800   If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
 801   each individual brace case should be handled. Otherwise, this is ignored.
 802
 803   .. code-block:: yaml
 804
 805     # Example of usage:
 806     BreakBeforeBraces: Custom
 807     BraceWrapping:
 808       AfterEnum: true
 809       AfterStruct: false
 810       SplitEmptyFunction: false
 811
 812   Nested configuration flags:
 813
 814
 815   * ``bool AfterCaseLabel`` Wrap case labels.
 816
 817     .. code-block:: c++
 818
 819       false:                                true:
 820       switch (foo) {                vs.     switch (foo) {
 821         case 1: {                             case 1:
 822           bar();                              {
 823           break;                                bar();
 824         }                                       break;
 825         default: {                            }
 826           plop();                             default:
 827         }                                     {
 828       }                                         plop();
 829                                               }
 830                                             }
 831
 832   * ``bool AfterClass`` Wrap class definitions.
 833
 834     .. code-block:: c++
 835
 836       true:
 837       class foo {};
 838
 839       false:
 840       class foo
 841       {};
 842
 843   * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
 844     Wrap control statements (``if``/``for``/``while``/``switch``/..).
 845
 846     Possible values:
 847
 848     * ``BWACS_Never`` (in configuration: ``Never``)
 849       Never wrap braces after a control statement.
 850
 851       .. code-block:: c++
 852
 853         if (foo()) {
 854         } else {
 855         }
 856         for (int i = 0; i < 10; ++i) {
 857         }
 858
 859     * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
 860       Only wrap braces after a multi-line control statement.
 861
 862       .. code-block:: c++
 863
 864         if (foo && bar &&
 865             baz)
 866         {
 867           quux();
 868         }
 869         while (foo || bar) {
 870         }
 871
 872     * ``BWACS_Always`` (in configuration: ``Always``)
 873       Always wrap braces after a control statement.
 874
 875       .. code-block:: c++
 876
 877         if (foo())
 878         {
 879         } else
 880         {}
 881         for (int i = 0; i < 10; ++i)
 882         {}
 883
 884
 885   * ``bool AfterEnum`` Wrap enum definitions.
 886
 887     .. code-block:: c++
 888
 889       true:
 890       enum X : int
 891       {
 892         B
 893       };
 894
 895       false:
 896       enum X : int { B };
 897
 898   * ``bool AfterFunction`` Wrap function definitions.
 899
 900     .. code-block:: c++
 901
 902       true:
 903       void foo()
 904       {
 905         bar();
 906         bar2();
 907       }
 908
 909       false:
 910       void foo() {
 911         bar();
 912         bar2();
 913       }
 914
 915   * ``bool AfterNamespace`` Wrap namespace definitions.
 916
 917     .. code-block:: c++
 918
 919       true:
 920       namespace
 921       {
 922       int foo();
 923       int bar();
 924       }
 925
 926       false:
 927       namespace {
 928       int foo();
 929       int bar();
 930       }
 931
 932   * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
 933     @autoreleasepool and @synchronized blocks are wrapped
 934     according to `AfterControlStatement` flag.
 935
 936   * ``bool AfterStruct`` Wrap struct definitions.
 937
 938     .. code-block:: c++
 939
 940       true:
 941       struct foo
 942       {
 943         int x;
 944       };
 945
 946       false:
 947       struct foo {
 948         int x;
 949       };
 950
 951   * ``bool AfterUnion`` Wrap union definitions.
 952
 953     .. code-block:: c++
 954
 955       true:
 956       union foo
 957       {
 958         int x;
 959       }
 960
 961       false:
 962       union foo {
 963         int x;
 964       }
 965
 966   * ``bool AfterExternBlock`` Wrap extern blocks.
 967
 968     .. code-block:: c++
 969
 970       true:
 971       extern "C"
 972       {
 973         int foo();
 974       }
 975
 976       false:
 977       extern "C" {
 978       int foo();
 979       }
 980
 981   * ``bool BeforeCatch`` Wrap before ``catch``.
 982
 983     .. code-block:: c++
 984
 985       true:
 986       try {
 987         foo();
 988       }
 989       catch () {
 990       }
 991
 992       false:
 993       try {
 994         foo();
 995       } catch () {
 996       }
 997
 998   * ``bool BeforeElse`` Wrap before ``else``.
 999
1000     .. code-block:: c++
1001
1002       true:
1003       if (foo()) {
1004       }
1005       else {
1006       }
1007
1008       false:
1009       if (foo()) {
1010       } else {
1011       }
1012
1013   * ``bool BeforeLambdaBody`` Wrap lambda block.
1014
1015     .. code-block:: c++
1016
1017       true:
1018       connect(
1019         []()
1020         {
1021           foo();
1022           bar();
1023         });
1024
1025       false:
1026       connect([]() {
1027         foo();
1028         bar();
1029       });
1030
1031   * ``bool BeforeWhile`` Wrap before ``while``.
1032
1033     .. code-block:: c++
1034
1035       true:
1036       do {
1037         foo();
1038       }
1039       while (1);
1040
1041       false:
1042       do {
1043         foo();
1044       } while (1);
1045
1046   * ``bool IndentBraces`` Indent the wrapped braces themselves.
1047
1048   * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
1049     This option is used only if the opening brace of the function has
1050     already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
1051     set, and the function could/should not be put on a single line (as per
1052     `AllowShortFunctionsOnASingleLine` and constructor formatting options).
1053
1054     .. code-block:: c++
1055
1056       int f()   vs.   int f()
1057       {}              {
1058                       }
1059
1060   * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
1061     can be put on a single line. This option is used only if the opening
1062     brace of the record has already been wrapped, i.e. the `AfterClass`
1063     (for classes) brace wrapping mode is set.
1064
1065     .. code-block:: c++
1066
1067       class Foo   vs.  class Foo
1068       {}               {
1069                        }
1070
1071   * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
1072     This option is used only if the opening brace of the namespace has
1073     already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
1074     set.
1075
1076     .. code-block:: c++
1077
1078       namespace Foo   vs.  namespace Foo
1079       {}                   {
1080                            }
1081
1082
1083 **BreakAfterJavaFieldAnnotations** (``bool``)
1084   Break after each annotation on a field in Java files.
1085
1086   .. code-block:: java
1087
1088      true:                                  false:
1089      @Partial                       vs.     @Partial @Mock DataLoad loader;
1090      @Mock
1091      DataLoad loader;
1092
1093 **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
1094   The way to wrap binary operators.
1095
1096   Possible values:
1097
1098   * ``BOS_None`` (in configuration: ``None``)
1099     Break after operators.
1100
1101     .. code-block:: c++
1102
1103        LooooooooooongType loooooooooooooooooooooongVariable =
1104            someLooooooooooooooooongFunction();
1105
1106        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
1107                             aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
1108                         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
1109                     aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
1110                         ccccccccccccccccccccccccccccccccccccccccc;
1111
1112   * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
1113     Break before operators that aren't assignments.
1114
1115     .. code-block:: c++
1116
1117        LooooooooooongType loooooooooooooooooooooongVariable =
1118            someLooooooooooooooooongFunction();
1119
1120        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1121                             + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1122                         == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1123                     && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1124                            > ccccccccccccccccccccccccccccccccccccccccc;
1125
1126   * ``BOS_All`` (in configuration: ``All``)
1127     Break before operators.
1128
1129     .. code-block:: c++
1130
1131        LooooooooooongType loooooooooooooooooooooongVariable
1132            = someLooooooooooooooooongFunction();
1133
1134        bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1135                             + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1136                         == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1137                     && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1138                            > ccccccccccccccccccccccccccccccccccccccccc;
1139
1140
1141
1142 **BreakBeforeBraces** (``BraceBreakingStyle``)
1143   The brace breaking style to use.
1144
1145   Possible values:
1146
1147   * ``BS_Attach`` (in configuration: ``Attach``)
1148     Always attach braces to surrounding context.
1149
1150     .. code-block:: c++
1151
1152       try {
1153         foo();
1154       } catch () {
1155       }
1156       void foo() { bar(); }
1157       class foo {};
1158       if (foo()) {
1159       } else {
1160       }
1161       enum X : int { A, B };
1162
1163   * ``BS_Linux`` (in configuration: ``Linux``)
1164     Like ``Attach``, but break before braces on function, namespace and
1165     class definitions.
1166
1167     .. code-block:: c++
1168
1169       try {
1170         foo();
1171       } catch () {
1172       }
1173       void foo() { bar(); }
1174       class foo
1175       {
1176       };
1177       if (foo()) {
1178       } else {
1179       }
1180       enum X : int { A, B };
1181
1182   * ``BS_Mozilla`` (in configuration: ``Mozilla``)
1183     Like ``Attach``, but break before braces on enum, function, and record
1184     definitions.
1185
1186     .. code-block:: c++
1187
1188       try {
1189         foo();
1190       } catch () {
1191       }
1192       void foo() { bar(); }
1193       class foo
1194       {
1195       };
1196       if (foo()) {
1197       } else {
1198       }
1199       enum X : int { A, B };
1200
1201   * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
1202     Like ``Attach``, but break before function definitions, ``catch``, and
1203     ``else``.
1204
1205     .. code-block:: c++
1206
1207       try {
1208         foo();
1209       }
1210       catch () {
1211       }
1212       void foo() { bar(); }
1213       class foo {
1214       };
1215       if (foo()) {
1216       }
1217       else {
1218       }
1219       enum X : int { A, B };
1220
1221   * ``BS_Allman`` (in configuration: ``Allman``)
1222     Always break before braces.
1223
1224     .. code-block:: c++
1225
1226       try
1227       {
1228         foo();
1229       }
1230       catch ()
1231       {
1232       }
1233       void foo() { bar(); }
1234       class foo
1235       {
1236       };
1237       if (foo())
1238       {
1239       }
1240       else
1241       {
1242       }
1243       enum X : int
1244       {
1245         A,
1246         B
1247       };
1248
1249   * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``)
1250     Like ``Allman`` but always indent braces and line up code with braces.
1251
1252     .. code-block:: c++
1253
1254       try
1255         {
1256         foo();
1257         }
1258       catch ()
1259         {
1260         }
1261       void foo() { bar(); }
1262       class foo
1263         {
1264         };
1265       if (foo())
1266         {
1267         }
1268       else
1269         {
1270         }
1271       enum X : int
1272         {
1273         A,
1274         B
1275         };
1276
1277   * ``BS_GNU`` (in configuration: ``GNU``)
1278     Always break before braces and add an extra level of indentation to
1279     braces of control statements, not to those of class, function
1280     or other definitions.
1281
1282     .. code-block:: c++
1283
1284       try
1285         {
1286           foo();
1287         }
1288       catch ()
1289         {
1290         }
1291       void foo() { bar(); }
1292       class foo
1293       {
1294       };
1295       if (foo())
1296         {
1297         }
1298       else
1299         {
1300         }
1301       enum X : int
1302       {
1303         A,
1304         B
1305       };
1306
1307   * ``BS_WebKit`` (in configuration: ``WebKit``)
1308     Like ``Attach``, but break before functions.
1309
1310     .. code-block:: c++
1311
1312       try {
1313         foo();
1314       } catch () {
1315       }
1316       void foo() { bar(); }
1317       class foo {
1318       };
1319       if (foo()) {
1320       } else {
1321       }
1322       enum X : int { A, B };
1323
1324   * ``BS_Custom`` (in configuration: ``Custom``)
1325     Configure each individual brace in `BraceWrapping`.
1326
1327
1328
1329 **BreakBeforeTernaryOperators** (``bool``)
1330   If ``true``, ternary operators will be placed after line breaks.
1331
1332   .. code-block:: c++
1333
1334      true:
1335      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
1336          ? firstValue
1337          : SecondValueVeryVeryVeryVeryLong;
1338
1339      false:
1340      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
1341          firstValue :
1342          SecondValueVeryVeryVeryVeryLong;
1343
1344 **BreakConstructorInitializers** (``BreakConstructorInitializersStyle``)
1345   The constructor initializers style to use.
1346
1347   Possible values:
1348
1349   * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
1350     Break constructor initializers before the colon and after the commas.
1351
1352     .. code-block:: c++
1353
1354        Constructor()
1355            : initializer1(),
1356              initializer2()
1357
1358   * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
1359     Break constructor initializers before the colon and commas, and align
1360     the commas with the colon.
1361
1362     .. code-block:: c++
1363
1364        Constructor()
1365            : initializer1()
1366            , initializer2()
1367
1368   * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
1369     Break constructor initializers after the colon and commas.
1370
1371     .. code-block:: c++
1372
1373        Constructor() :
1374            initializer1(),
1375            initializer2()
1376
1377
1378
1379 **BreakInheritanceList** (``BreakInheritanceListStyle``)
1380   The inheritance list style to use.
1381
1382   Possible values:
1383
1384   * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
1385     Break inheritance list before the colon and after the commas.
1386
1387     .. code-block:: c++
1388
1389        class Foo
1390            : Base1,
1391              Base2
1392        {};
1393
1394   * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
1395     Break inheritance list before the colon and commas, and align
1396     the commas with the colon.
1397
1398     .. code-block:: c++
1399
1400        class Foo
1401            : Base1
1402            , Base2
1403        {};
1404
1405   * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
1406     Break inheritance list after the colon and commas.
1407
1408     .. code-block:: c++
1409
1410        class Foo :
1411            Base1,
1412            Base2
1413        {};
1414
1415
1416
1417 **BreakStringLiterals** (``bool``)
1418   Allow breaking string literals when formatting.
1419
1420   .. code-block:: c++
1421
1422      true:
1423      const char* x = "veryVeryVeryVeryVeryVe"
1424                      "ryVeryVeryVeryVeryVery"
1425                      "VeryLongString";
1426
1427      false:
1428      const char* x =
1429        "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
1430
1431 **ColumnLimit** (``unsigned``)
1432   The column limit.
1433
1434   A column limit of ``0`` means that there is no column limit. In this case,
1435   clang-format will respect the input's line breaking decisions within
1436   statements unless they contradict other rules.
1437
1438 **CommentPragmas** (``std::string``)
1439   A regular expression that describes comments with special meaning,
1440   which should not be split into lines or otherwise changed.
1441
1442   .. code-block:: c++
1443
1444      // CommentPragmas: '^ FOOBAR pragma:'
1445      // Will leave the following line unaffected
1446      #include <vector> // FOOBAR pragma: keep
1447
1448 **CompactNamespaces** (``bool``)
1449   If ``true``, consecutive namespace declarations will be on the same
1450   line. If ``false``, each namespace is declared on a new line.
1451
1452   .. code-block:: c++
1453
1454     true:
1455     namespace Foo { namespace Bar {
1456     }}
1457
1458     false:
1459     namespace Foo {
1460     namespace Bar {
1461     }
1462     }
1463
1464   If it does not fit on a single line, the overflowing namespaces get
1465   wrapped:
1466
1467   .. code-block:: c++
1468
1469     namespace Foo { namespace Bar {
1470     namespace Extra {
1471     }}}
1472
1473 **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
1474   If the constructor initializers don't fit on a line, put each
1475   initializer on its own line.
1476
1477   .. code-block:: c++
1478
1479     true:
1480     SomeClass::Constructor()
1481         : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1482       return 0;
1483     }
1484
1485     false:
1486     SomeClass::Constructor()
1487         : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
1488           aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1489       return 0;
1490     }
1491
1492 **ConstructorInitializerIndentWidth** (``unsigned``)
1493   The number of characters to use for indentation of constructor
1494   initializer lists as well as inheritance lists.
1495
1496 **ContinuationIndentWidth** (``unsigned``)
1497   Indent width for line continuations.
1498
1499   .. code-block:: c++
1500
1501      ContinuationIndentWidth: 2
1502
1503      int i =         //  VeryVeryVeryVeryVeryLongComment
1504        longFunction( // Again a long comment
1505          arg);
1506
1507 **Cpp11BracedListStyle** (``bool``)
1508   If ``true``, format braced lists as best suited for C++11 braced
1509   lists.
1510
1511   Important differences:
1512   - No spaces inside the braced list.
1513   - No line break before the closing brace.
1514   - Indentation with the continuation indent, not with the block indent.
1515
1516   Fundamentally, C++11 braced lists are formatted exactly like function
1517   calls would be formatted in their place. If the braced list follows a name
1518   (e.g. a type or variable name), clang-format formats as if the ``{}`` were
1519   the parentheses of a function call with that name. If there is no name,
1520   a zero-length name is assumed.
1521
1522   .. code-block:: c++
1523
1524      true:                                  false:
1525      vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
1526      vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
1527      f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
1528      new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
1529
1530 **DeriveLineEnding** (``bool``)
1531   Analyze the formatted file for the most used line ending (``\r\n``
1532   or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived.
1533
1534 **DerivePointerAlignment** (``bool``)
1535   If ``true``, analyze the formatted file for the most common
1536   alignment of ``&`` and ``*``.
1537   Pointer and reference alignment styles are going to be updated according
1538   to the preferences found in the file.
1539   ``PointerAlignment`` is then used only as fallback.
1540
1541 **DisableFormat** (``bool``)
1542   Disables formatting completely.
1543
1544 **ExperimentalAutoDetectBinPacking** (``bool``)
1545   If ``true``, clang-format detects whether function calls and
1546   definitions are formatted with one parameter per line.
1547
1548   Each call can be bin-packed, one-per-line or inconclusive. If it is
1549   inconclusive, e.g. completely on one line, but a decision needs to be
1550   made, clang-format analyzes whether there are other bin-packed cases in
1551   the input file and act accordingly.
1552
1553   NOTE: This is an experimental flag, that might go away or be renamed. Do
1554   not use this in config files, etc. Use at your own risk.
1555
1556 **FixNamespaceComments** (``bool``)
1557   If ``true``, clang-format adds missing namespace end comments and
1558   fixes invalid existing ones.
1559
1560   .. code-block:: c++
1561
1562      true:                                  false:
1563      namespace a {                  vs.     namespace a {
1564      foo();                                 foo();
1565      } // namespace a                       }
1566
1567 **ForEachMacros** (``std::vector<std::string>``)
1568   A vector of macros that should be interpreted as foreach loops
1569   instead of as function calls.
1570
1571   These are expected to be macros of the form:
1572
1573   .. code-block:: c++
1574
1575     FOREACH(<variable-declaration>, ...)
1576       <loop-body>
1577
1578   In the .clang-format configuration file, this can be configured like:
1579
1580   .. code-block:: yaml
1581
1582     ForEachMacros: ['RANGES_FOR', 'FOREACH']
1583
1584   For example: BOOST_FOREACH.
1585
1586 **IncludeBlocks** (``IncludeBlocksStyle``)
1587   Dependent on the value, multiple ``#include`` blocks can be sorted
1588   as one and divided based on category.
1589
1590   Possible values:
1591
1592   * ``IBS_Preserve`` (in configuration: ``Preserve``)
1593     Sort each ``#include`` block separately.
1594
1595     .. code-block:: c++
1596
1597        #include "b.h"               into      #include "b.h"
1598
1599        #include <lib/main.h>                  #include "a.h"
1600        #include "a.h"                         #include <lib/main.h>
1601
1602   * ``IBS_Merge`` (in configuration: ``Merge``)
1603     Merge multiple ``#include`` blocks together and sort as one.
1604
1605     .. code-block:: c++
1606
1607        #include "b.h"               into      #include "a.h"
1608                                               #include "b.h"
1609        #include <lib/main.h>                  #include <lib/main.h>
1610        #include "a.h"
1611
1612   * ``IBS_Regroup`` (in configuration: ``Regroup``)
1613     Merge multiple ``#include`` blocks together and sort as one.
1614     Then split into groups based on category priority. See
1615     ``IncludeCategories``.
1616
1617     .. code-block:: c++
1618
1619        #include "b.h"               into      #include "a.h"
1620                                               #include "b.h"
1621        #include <lib/main.h>
1622        #include "a.h"                         #include <lib/main.h>
1623
1624
1625
1626 **IncludeCategories** (``std::vector<IncludeCategory>``)
1627   Regular expressions denoting the different ``#include`` categories
1628   used for ordering ``#includes``.
1629
1630   `POSIX extended
1631   <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
1632   regular expressions are supported.
1633
1634   These regular expressions are matched against the filename of an include
1635   (including the <> or "") in order. The value belonging to the first
1636   matching regular expression is assigned and ``#includes`` are sorted first
1637   according to increasing category number and then alphabetically within
1638   each category.
1639
1640   If none of the regular expressions match, INT_MAX is assigned as
1641   category. The main header for a source file automatically gets category 0.
1642   so that it is generally kept at the beginning of the ``#includes``
1643   (https://llvm.org/docs/CodingStandards.html#include-style). However, you
1644   can also assign negative priorities if you have certain headers that
1645   always need to be first.
1646
1647   There is a third and optional field ``SortPriority`` which can used while
1648   ``IncludeBloks = IBS_Regroup`` to define the priority in which ``#includes``
1649   should be ordered, and value of ``Priority`` defines the order of
1650   ``#include blocks`` and also enables to group ``#includes`` of different
1651   priority for order.``SortPriority`` is set to the value of ``Priority``
1652   as default if it is not assigned.
1653
1654   To configure this in the .clang-format file, use:
1655
1656   .. code-block:: yaml
1657
1658     IncludeCategories:
1659       - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
1660         Priority:        2
1661         SortPriority:    2
1662       - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
1663         Priority:        3
1664       - Regex:           '<[[:alnum:].]+>'
1665         Priority:        4
1666       - Regex:           '.*'
1667         Priority:        1
1668         SortPriority:    0
1669
1670 **IncludeIsMainRegex** (``std::string``)
1671   Specify a regular expression of suffixes that are allowed in the
1672   file-to-main-include mapping.
1673
1674   When guessing whether a #include is the "main" include (to assign
1675   category 0, see above), use this regex of allowed suffixes to the header
1676   stem. A partial match is done, so that:
1677   - "" means "arbitrary suffix"
1678   - "$" means "no suffix"
1679
1680   For example, if configured to "(_test)?$", then a header a.h would be seen
1681   as the "main" include in both a.cc and a_test.cc.
1682
1683 **IncludeIsMainSourceRegex** (``std::string``)
1684   Specify a regular expression for files being formatted
1685   that are allowed to be considered "main" in the
1686   file-to-main-include mapping.
1687
1688   By default, clang-format considers files as "main" only when they end
1689   with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm``
1690   extensions.
1691   For these files a guessing of "main" include takes place
1692   (to assign category 0, see above). This config option allows for
1693   additional suffixes and extensions for files to be considered as "main".
1694
1695   For example, if this option is configured to ``(Impl\.hpp)$``,
1696   then a file ``ClassImpl.hpp`` is considered "main" (in addition to
1697   ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
1698   include file" logic will be executed (with *IncludeIsMainRegex* setting
1699   also being respected in later phase). Without this option set,
1700   ``ClassImpl.hpp`` would not have the main include file put on top
1701   before any other include.
1702
1703 **IndentCaseBlocks** (``bool``)
1704   Indent case label blocks one level from the case label.
1705
1706   When ``false``, the block following the case label uses the same
1707   indentation level as for the case label, treating the case label the same
1708   as an if-statement.
1709   When ``true``, the block gets indented as a scope block.
1710
1711   .. code-block:: c++
1712
1713      false:                                 true:
1714      switch (fool) {                vs.     switch (fool) {
1715      case 1: {                              case 1:
1716        bar();                                 {
1717      } break;                                   bar();
1718      default: {                               }
1719        plop();                                break;
1720      }                                      default:
1721      }                                        {
1722                                                 plop();
1723                                               }
1724                                             }
1725
1726 **IndentCaseLabels** (``bool``)
1727   Indent case labels one level from the switch statement.
1728
1729   When ``false``, use the same indentation level as for the switch
1730   statement. Switch statement body is always indented one level more than
1731   case labels (except the first block following the case label, which
1732   itself indents the code - unless IndentCaseBlocks is enabled).
1733
1734   .. code-block:: c++
1735
1736      false:                                 true:
1737      switch (fool) {                vs.     switch (fool) {
1738      case 1:                                  case 1:
1739        bar();                                   bar();
1740        break;                                   break;
1741      default:                                 default:
1742        plop();                                  plop();
1743      }                                      }
1744
1745 **IndentExternBlock** (``IndentExternBlockStyle``)
1746   IndentExternBlockStyle is the type of indenting of extern blocks.
1747
1748   Possible values:
1749
1750   * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``)
1751     Backwards compatible with AfterExternBlock's indenting.
1752
1753     .. code-block:: c++
1754
1755        IndentExternBlock: AfterExternBlock
1756        BraceWrapping.AfterExternBlock: true
1757        extern "C"
1758        {
1759            void foo();
1760        }
1761
1762
1763     .. code-block:: c++
1764
1765        IndentExternBlock: AfterExternBlock
1766        BraceWrapping.AfterExternBlock: false
1767        extern "C" {
1768        void foo();
1769        }
1770
1771   * ``IEBS_NoIndent`` (in configuration: ``NoIndent``)
1772     Does not indent extern blocks.
1773
1774     .. code-block:: c++
1775
1776         extern "C" {
1777         void foo();
1778         }
1779
1780   * ``IEBS_Indent`` (in configuration: ``Indent``)
1781     Indents extern blocks.
1782
1783     .. code-block:: c++
1784
1785         extern "C" {
1786           void foo();
1787         }
1788
1789
1790
1791 **IndentGotoLabels** (``bool``)
1792   Indent goto labels.
1793
1794   When ``false``, goto labels are flushed left.
1795
1796   .. code-block:: c++
1797
1798      true:                                  false:
1799      int f() {                      vs.     int f() {
1800        if (foo()) {                           if (foo()) {
1801        label1:                              label1:
1802          bar();                                 bar();
1803        }                                      }
1804      label2:                                label2:
1805        return 1;                              return 1;
1806      }                                      }
1807
1808 **IndentPPDirectives** (``PPDirectiveIndentStyle``)
1809   The preprocessor directive indenting style to use.
1810
1811   Possible values:
1812
1813   * ``PPDIS_None`` (in configuration: ``None``)
1814     Does not indent any directives.
1815
1816     .. code-block:: c++
1817
1818        #if FOO
1819        #if BAR
1820        #include <foo>
1821        #endif
1822        #endif
1823
1824   * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
1825     Indents directives after the hash.
1826
1827     .. code-block:: c++
1828
1829        #if FOO
1830        #  if BAR
1831        #    include <foo>
1832        #  endif
1833        #endif
1834
1835   * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
1836     Indents directives before the hash.
1837
1838     .. code-block:: c++
1839
1840        #if FOO
1841          #if BAR
1842            #include <foo>
1843          #endif
1844        #endif
1845
1846
1847
1848 **IndentWidth** (``unsigned``)
1849   The number of columns to use for indentation.
1850
1851   .. code-block:: c++
1852
1853      IndentWidth: 3
1854
1855      void f() {
1856         someFunction();
1857         if (true, false) {
1858            f();
1859         }
1860      }
1861
1862 **IndentWrappedFunctionNames** (``bool``)
1863   Indent if a function definition or declaration is wrapped after the
1864   type.
1865
1866   .. code-block:: c++
1867
1868      true:
1869      LoooooooooooooooooooooooooooooooooooooooongReturnType
1870          LoooooooooooooooooooooooooooooooongFunctionDeclaration();
1871
1872      false:
1873      LoooooooooooooooooooooooooooooooooooooooongReturnType
1874      LoooooooooooooooooooooooooooooooongFunctionDeclaration();
1875
1876 **InsertTrailingCommas** (``TrailingCommaStyle``)
1877   If set to ``TCS_Wrapped`` will insert trailing commas in container
1878   literals (arrays and objects) that wrap across multiple lines.
1879   It is currently only available for JavaScript
1880   and disabled by default ``TCS_None``.
1881   ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
1882   as inserting the comma disables bin-packing.
1883
1884   .. code-block:: c++
1885
1886     TSC_Wrapped:
1887     const someArray = [
1888     aaaaaaaaaaaaaaaaaaaaaaaaaa,
1889     aaaaaaaaaaaaaaaaaaaaaaaaaa,
1890     aaaaaaaaaaaaaaaaaaaaaaaaaa,
1891     //                        ^ inserted
1892     ]
1893
1894   Possible values:
1895
1896   * ``TCS_None`` (in configuration: ``None``)
1897     Do not insert trailing commas.
1898
1899   * ``TCS_Wrapped`` (in configuration: ``Wrapped``)
1900     Insert trailing commas in container literals that were wrapped over
1901     multiple lines. Note that this is conceptually incompatible with
1902     bin-packing, because the trailing comma is used as an indicator
1903     that a container should be formatted one-per-line (i.e. not bin-packed).
1904     So inserting a trailing comma counteracts bin-packing.
1905
1906
1907
1908 **JavaImportGroups** (``std::vector<std::string>``)
1909   A vector of prefixes ordered by the desired groups for Java imports.
1910
1911   Each group is separated by a newline. Static imports will also follow the
1912   same grouping convention above all non-static imports. One group's prefix
1913   can be a subset of another - the longest prefix is always matched. Within
1914   a group, the imports are ordered lexicographically.
1915
1916   In the .clang-format configuration file, this can be configured like
1917   in the following yaml example. This will result in imports being
1918   formatted as in the Java example below.
1919
1920   .. code-block:: yaml
1921
1922     JavaImportGroups: ['com.example', 'com', 'org']
1923
1924
1925   .. code-block:: java
1926
1927      import static com.example.function1;
1928
1929      import static com.test.function2;
1930
1931      import static org.example.function3;
1932
1933      import com.example.ClassA;
1934      import com.example.Test;
1935      import com.example.a.ClassB;
1936
1937      import com.test.ClassC;
1938
1939      import org.example.ClassD;
1940
1941 **JavaScriptQuotes** (``JavaScriptQuoteStyle``)
1942   The JavaScriptQuoteStyle to use for JavaScript strings.
1943
1944   Possible values:
1945
1946   * ``JSQS_Leave`` (in configuration: ``Leave``)
1947     Leave string quotes as they are.
1948
1949     .. code-block:: js
1950
1951        string1 = "foo";
1952        string2 = 'bar';
1953
1954   * ``JSQS_Single`` (in configuration: ``Single``)
1955     Always use single quotes.
1956
1957     .. code-block:: js
1958
1959        string1 = 'foo';
1960        string2 = 'bar';
1961
1962   * ``JSQS_Double`` (in configuration: ``Double``)
1963     Always use double quotes.
1964
1965     .. code-block:: js
1966
1967        string1 = "foo";
1968        string2 = "bar";
1969
1970
1971
1972 **JavaScriptWrapImports** (``bool``)
1973   Whether to wrap JavaScript import/export statements.
1974
1975   .. code-block:: js
1976
1977      true:
1978      import {
1979          VeryLongImportsAreAnnoying,
1980          VeryLongImportsAreAnnoying,
1981          VeryLongImportsAreAnnoying,
1982      } from 'some/module.js'
1983
1984      false:
1985      import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
1986
1987 **KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
1988   If true, the empty line at the start of blocks is kept.
1989
1990   .. code-block:: c++
1991
1992      true:                                  false:
1993      if (foo) {                     vs.     if (foo) {
1994                                               bar();
1995        bar();                               }
1996      }
1997
1998 **Language** (``LanguageKind``)
1999   Language, this format style is targeted at.
2000
2001   Possible values:
2002
2003   * ``LK_None`` (in configuration: ``None``)
2004     Do not use.
2005
2006   * ``LK_Cpp`` (in configuration: ``Cpp``)
2007     Should be used for C, C++.
2008
2009   * ``LK_CSharp`` (in configuration: ``CSharp``)
2010     Should be used for C#.
2011
2012   * ``LK_Java`` (in configuration: ``Java``)
2013     Should be used for Java.
2014
2015   * ``LK_JavaScript`` (in configuration: ``JavaScript``)
2016     Should be used for JavaScript.
2017
2018   * ``LK_ObjC`` (in configuration: ``ObjC``)
2019     Should be used for Objective-C, Objective-C++.
2020
2021   * ``LK_Proto`` (in configuration: ``Proto``)
2022     Should be used for Protocol Buffers
2023     (https://developers.google.com/protocol-buffers/).
2024
2025   * ``LK_TableGen`` (in configuration: ``TableGen``)
2026     Should be used for TableGen code.
2027
2028   * ``LK_TextProto`` (in configuration: ``TextProto``)
2029     Should be used for Protocol Buffer messages in text format
2030     (https://developers.google.com/protocol-buffers/).
2031
2032
2033
2034 **MacroBlockBegin** (``std::string``)
2035   A regular expression matching macros that start a block.
2036
2037   .. code-block:: c++
2038
2039      # With:
2040      MacroBlockBegin: "^NS_MAP_BEGIN|\
2041      NS_TABLE_HEAD$"
2042      MacroBlockEnd: "^\
2043      NS_MAP_END|\
2044      NS_TABLE_.*_END$"
2045
2046      NS_MAP_BEGIN
2047        foo();
2048      NS_MAP_END
2049
2050      NS_TABLE_HEAD
2051        bar();
2052      NS_TABLE_FOO_END
2053
2054      # Without:
2055      NS_MAP_BEGIN
2056      foo();
2057      NS_MAP_END
2058
2059      NS_TABLE_HEAD
2060      bar();
2061      NS_TABLE_FOO_END
2062
2063 **MacroBlockEnd** (``std::string``)
2064   A regular expression matching macros that end a block.
2065
2066 **MaxEmptyLinesToKeep** (``unsigned``)
2067   The maximum number of consecutive empty lines to keep.
2068
2069   .. code-block:: c++
2070
2071      MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 0
2072      int f() {                              int f() {
2073        int = 1;                                 int i = 1;
2074                                                 i = foo();
2075        i = foo();                               return i;
2076                                             }
2077        return i;
2078      }
2079
2080 **NamespaceIndentation** (``NamespaceIndentationKind``)
2081   The indentation used for namespaces.
2082
2083   Possible values:
2084
2085   * ``NI_None`` (in configuration: ``None``)
2086     Don't indent in namespaces.
2087
2088     .. code-block:: c++
2089
2090        namespace out {
2091        int i;
2092        namespace in {
2093        int i;
2094        }
2095        }
2096
2097   * ``NI_Inner`` (in configuration: ``Inner``)
2098     Indent only in inner namespaces (nested in other namespaces).
2099
2100     .. code-block:: c++
2101
2102        namespace out {
2103        int i;
2104        namespace in {
2105          int i;
2106        }
2107        }
2108
2109   * ``NI_All`` (in configuration: ``All``)
2110     Indent in all namespaces.
2111
2112     .. code-block:: c++
2113
2114        namespace out {
2115          int i;
2116          namespace in {
2117            int i;
2118          }
2119        }
2120
2121
2122
2123 **NamespaceMacros** (``std::vector<std::string>``)
2124   A vector of macros which are used to open namespace blocks.
2125
2126   These are expected to be macros of the form:
2127
2128   .. code-block:: c++
2129
2130     NAMESPACE(<namespace-name>, ...) {
2131       <namespace-content>
2132     }
2133
2134   For example: TESTSUITE
2135
2136 **ObjCBinPackProtocolList** (``BinPackStyle``)
2137   Controls bin-packing Objective-C protocol conformance list
2138   items into as few lines as possible when they go over ``ColumnLimit``.
2139
2140   If ``Auto`` (the default), delegates to the value in
2141   ``BinPackParameters``. If that is ``true``, bin-packs Objective-C
2142   protocol conformance list items into as few lines as possible
2143   whenever they go over ``ColumnLimit``.
2144
2145   If ``Always``, always bin-packs Objective-C protocol conformance
2146   list items into as few lines as possible whenever they go over
2147   ``ColumnLimit``.
2148
2149   If ``Never``, lays out Objective-C protocol conformance list items
2150   onto individual lines whenever they go over ``ColumnLimit``.
2151
2152
2153   .. code-block:: objc
2154
2155      Always (or Auto, if BinPackParameters=true):
2156      @interface ccccccccccccc () <
2157          ccccccccccccc, ccccccccccccc,
2158          ccccccccccccc, ccccccccccccc> {
2159      }
2160
2161      Never (or Auto, if BinPackParameters=false):
2162      @interface ddddddddddddd () <
2163          ddddddddddddd,
2164          ddddddddddddd,
2165          ddddddddddddd,
2166          ddddddddddddd> {
2167      }
2168
2169   Possible values:
2170
2171   * ``BPS_Auto`` (in configuration: ``Auto``)
2172     Automatically determine parameter bin-packing behavior.
2173
2174   * ``BPS_Always`` (in configuration: ``Always``)
2175     Always bin-pack parameters.
2176
2177   * ``BPS_Never`` (in configuration: ``Never``)
2178     Never bin-pack parameters.
2179
2180
2181
2182 **ObjCBlockIndentWidth** (``unsigned``)
2183   The number of characters to use for indentation of ObjC blocks.
2184
2185   .. code-block:: objc
2186
2187      ObjCBlockIndentWidth: 4
2188
2189      [operation setCompletionBlock:^{
2190          [self onOperationDone];
2191      }];
2192
2193 **ObjCBreakBeforeNestedBlockParam** (``bool``)
2194   Break parameters list into lines when there is nested block
2195   parameters in a fuction call.
2196
2197   .. code-block:: c++
2198
2199     false:
2200      - (void)_aMethod
2201      {
2202          [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
2203          *u, NSNumber *v) {
2204              u = c;
2205          }]
2206      }
2207      true:
2208      - (void)_aMethod
2209      {
2210         [self.test1 t:self
2211                      w:self
2212             callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
2213                  u = c;
2214              }]
2215      }
2216
2217 **ObjCSpaceAfterProperty** (``bool``)
2218   Add a space after ``@property`` in Objective-C, i.e. use
2219   ``@property (readonly)`` instead of ``@property(readonly)``.
2220
2221 **ObjCSpaceBeforeProtocolList** (``bool``)
2222   Add a space in front of an Objective-C protocol list, i.e. use
2223   ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
2224
2225 **PenaltyBreakAssignment** (``unsigned``)
2226   The penalty for breaking around an assignment operator.
2227
2228 **PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
2229   The penalty for breaking a function call after ``call(``.
2230
2231 **PenaltyBreakComment** (``unsigned``)
2232   The penalty for each line break introduced inside a comment.
2233
2234 **PenaltyBreakFirstLessLess** (``unsigned``)
2235   The penalty for breaking before the first ``<<``.
2236
2237 **PenaltyBreakString** (``unsigned``)
2238   The penalty for each line break introduced inside a string literal.
2239
2240 **PenaltyBreakTemplateDeclaration** (``unsigned``)
2241   The penalty for breaking after template declaration.
2242
2243 **PenaltyExcessCharacter** (``unsigned``)
2244   The penalty for each character outside of the column limit.
2245
2246 **PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
2247   Penalty for putting the return type of a function onto its own
2248   line.
2249
2250 **PointerAlignment** (``PointerAlignmentStyle``)
2251   Pointer and reference alignment style.
2252
2253   Possible values:
2254
2255   * ``PAS_Left`` (in configuration: ``Left``)
2256     Align pointer to the left.
2257
2258     .. code-block:: c++
2259
2260       int* a;
2261
2262   * ``PAS_Right`` (in configuration: ``Right``)
2263     Align pointer to the right.
2264
2265     .. code-block:: c++
2266
2267       int *a;
2268
2269   * ``PAS_Middle`` (in configuration: ``Middle``)
2270     Align pointer in the middle.
2271
2272     .. code-block:: c++
2273
2274       int * a;
2275
2276
2277
2278 **RawStringFormats** (``std::vector<RawStringFormat>``)
2279   Defines hints for detecting supported languages code blocks in raw
2280   strings.
2281
2282   A raw string with a matching delimiter or a matching enclosing function
2283   name will be reformatted assuming the specified language based on the
2284   style for that language defined in the .clang-format file. If no style has
2285   been defined in the .clang-format file for the specific language, a
2286   predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
2287   found, the formatting is based on llvm style. A matching delimiter takes
2288   precedence over a matching enclosing function name for determining the
2289   language of the raw string contents.
2290
2291   If a canonical delimiter is specified, occurrences of other delimiters for
2292   the same language will be updated to the canonical if possible.
2293
2294   There should be at most one specification per language and each delimiter
2295   and enclosing function should not occur in multiple specifications.
2296
2297   To configure this in the .clang-format file, use:
2298
2299   .. code-block:: yaml
2300
2301     RawStringFormats:
2302       - Language: TextProto
2303           Delimiters:
2304             - 'pb'
2305             - 'proto'
2306           EnclosingFunctions:
2307             - 'PARSE_TEXT_PROTO'
2308           BasedOnStyle: google
2309       - Language: Cpp
2310           Delimiters:
2311             - 'cc'
2312             - 'cpp'
2313           BasedOnStyle: llvm
2314           CanonicalDelimiter: 'cc'
2315
2316 **ReflowComments** (``bool``)
2317   If ``true``, clang-format will attempt to re-flow comments.
2318
2319   .. code-block:: c++
2320
2321      false:
2322      // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
2323      /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
2324
2325      true:
2326      // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
2327      // information
2328      /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
2329       * information */
2330
2331 **SortIncludes** (``bool``)
2332   If ``true``, clang-format will sort ``#includes``.
2333
2334   .. code-block:: c++
2335
2336      false:                                 true:
2337      #include "b.h"                 vs.     #include "a.h"
2338      #include "a.h"                         #include "b.h"
2339
2340 **SortUsingDeclarations** (``bool``)
2341   If ``true``, clang-format will sort using declarations.
2342
2343   The order of using declarations is defined as follows:
2344   Split the strings by "::" and discard any initial empty strings. The last
2345   element of each list is a non-namespace name; all others are namespace
2346   names. Sort the lists of names lexicographically, where the sort order of
2347   individual names is that all non-namespace names come before all namespace
2348   names, and within those groups, names are in case-insensitive
2349   lexicographic order.
2350
2351   .. code-block:: c++
2352
2353      false:                                 true:
2354      using std::cout;               vs.     using std::cin;
2355      using std::cin;                        using std::cout;
2356
2357 **SpaceAfterCStyleCast** (``bool``)
2358   If ``true``, a space is inserted after C style casts.
2359
2360   .. code-block:: c++
2361
2362      true:                                  false:
2363      (int) i;                       vs.     (int)i;
2364
2365 **SpaceAfterLogicalNot** (``bool``)
2366   If ``true``, a space is inserted after the logical not operator (``!``).
2367
2368   .. code-block:: c++
2369
2370      true:                                  false:
2371      ! someExpression();            vs.     !someExpression();
2372
2373 **SpaceAfterTemplateKeyword** (``bool``)
2374   If ``true``, a space will be inserted after the 'template' keyword.
2375
2376   .. code-block:: c++
2377
2378      true:                                  false:
2379      template <int> void foo();     vs.     template<int> void foo();
2380
2381 **SpaceBeforeAssignmentOperators** (``bool``)
2382   If ``false``, spaces will be removed before assignment operators.
2383
2384   .. code-block:: c++
2385
2386      true:                                  false:
2387      int a = 5;                     vs.     int a= 5;
2388      a += 42;                               a+= 42;
2389
2390 **SpaceBeforeCpp11BracedList** (``bool``)
2391   If ``true``, a space will be inserted before a C++11 braced list
2392   used to initialize an object (after the preceding identifier or type).
2393
2394   .. code-block:: c++
2395
2396      true:                                  false:
2397      Foo foo { bar };               vs.     Foo foo{ bar };
2398      Foo {};                                Foo{};
2399      vector<int> { 1, 2, 3 };               vector<int>{ 1, 2, 3 };
2400      new int[3] { 1, 2, 3 };                new int[3]{ 1, 2, 3 };
2401
2402 **SpaceBeforeCtorInitializerColon** (``bool``)
2403   If ``false``, spaces will be removed before constructor initializer
2404   colon.
2405
2406   .. code-block:: c++
2407
2408      true:                                  false:
2409      Foo::Foo() : a(a) {}                   Foo::Foo(): a(a) {}
2410
2411 **SpaceBeforeInheritanceColon** (``bool``)
2412   If ``false``, spaces will be removed before inheritance colon.
2413
2414   .. code-block:: c++
2415
2416      true:                                  false:
2417      class Foo : Bar {}             vs.     class Foo: Bar {}
2418
2419 **SpaceBeforeParens** (``SpaceBeforeParensOptions``)
2420   Defines in which cases to put a space before opening parentheses.
2421
2422   Possible values:
2423
2424   * ``SBPO_Never`` (in configuration: ``Never``)
2425     Never put a space before opening parentheses.
2426
2427     .. code-block:: c++
2428
2429        void f() {
2430          if(true) {
2431            f();
2432          }
2433        }
2434
2435   * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
2436     Put a space before opening parentheses only after control statement
2437     keywords (``for/if/while...``).
2438
2439     .. code-block:: c++
2440
2441        void f() {
2442          if (true) {
2443            f();
2444          }
2445        }
2446
2447   * ``SBPO_ControlStatementsExceptForEachMacros`` (in configuration: ``ControlStatementsExceptForEachMacros``)
2448     Same as ``SBPO_ControlStatements`` except this option doesn't apply to
2449     ForEach macros. This is useful in projects where ForEach macros are
2450     treated as function calls instead of control statements.
2451
2452     .. code-block:: c++
2453
2454        void f() {
2455          Q_FOREACH(...) {
2456            f();
2457          }
2458        }
2459
2460   * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``)
2461     Put a space before opening parentheses only if the parentheses are not
2462     empty i.e. '()'
2463
2464     .. code-block:: c++
2465
2466       void() {
2467         if (true) {
2468           f();
2469           g (x, y, z);
2470         }
2471       }
2472
2473   * ``SBPO_Always`` (in configuration: ``Always``)
2474     Always put a space before opening parentheses, except when it's
2475     prohibited by the syntax rules (in function-like macro definitions) or
2476     when determined by other style rules (after unary operators, opening
2477     parentheses, etc.)
2478
2479     .. code-block:: c++
2480
2481        void f () {
2482          if (true) {
2483            f ();
2484          }
2485        }
2486
2487
2488
2489 **SpaceBeforeRangeBasedForLoopColon** (``bool``)
2490   If ``false``, spaces will be removed before range-based for loop
2491   colon.
2492
2493   .. code-block:: c++
2494
2495      true:                                  false:
2496      for (auto v : values) {}       vs.     for(auto v: values) {}
2497
2498 **SpaceBeforeSquareBrackets** (``bool``)
2499   If ``true``, spaces will be before  ``[``.
2500   Lambdas will not be affected. Only the first ``[`` will get a space added.
2501
2502   .. code-block:: c++
2503
2504      true:                                  false:
2505      int a [5];                    vs.      int a[5];
2506      int a [5][5];                 vs.      int a[5][5];
2507
2508 **SpaceInEmptyBlock** (``bool``)
2509   If ``true``, spaces will be inserted into ``{}``.
2510
2511   .. code-block:: c++
2512
2513      true:                                false:
2514      void f() { }                   vs.   void f() {}
2515      while (true) { }                     while (true) {}
2516
2517 **SpaceInEmptyParentheses** (``bool``)
2518   If ``true``, spaces may be inserted into ``()``.
2519
2520   .. code-block:: c++
2521
2522      true:                                false:
2523      void f( ) {                    vs.   void f() {
2524        int x[] = {foo( ), bar( )};          int x[] = {foo(), bar()};
2525        if (true) {                          if (true) {
2526          f( );                                f();
2527        }                                    }
2528      }                                    }
2529
2530 **SpacesBeforeTrailingComments** (``unsigned``)
2531   The number of spaces before trailing line comments
2532   (``//`` - comments).
2533
2534   This does not affect trailing block comments (``/*`` - comments) as
2535   those commonly have different usage patterns and a number of special
2536   cases.
2537
2538   .. code-block:: c++
2539
2540      SpacesBeforeTrailingComments: 3
2541      void f() {
2542        if (true) {   // foo1
2543          f();        // bar
2544        }             // foo
2545      }
2546
2547 **SpacesInAngles** (``bool``)
2548   If ``true``, spaces will be inserted after ``<`` and before ``>``
2549   in template argument lists.
2550
2551   .. code-block:: c++
2552
2553      true:                                  false:
2554      static_cast< int >(arg);       vs.     static_cast<int>(arg);
2555      std::function< void(int) > fct;        std::function<void(int)> fct;
2556
2557 **SpacesInCStyleCastParentheses** (``bool``)
2558   If ``true``, spaces may be inserted into C style casts.
2559
2560   .. code-block:: c++
2561
2562      true:                                  false:
2563      x = ( int32 )y                 vs.     x = (int32)y
2564
2565 **SpacesInConditionalStatement** (``bool``)
2566   If ``true``, spaces will be inserted around if/for/switch/while
2567   conditions.
2568
2569   .. code-block:: c++
2570
2571      true:                                  false:
2572      if ( a )  { ... }              vs.     if (a) { ... }
2573      while ( i < 5 )  { ... }               while (i < 5) { ... }
2574
2575 **SpacesInContainerLiterals** (``bool``)
2576   If ``true``, spaces are inserted inside container literals (e.g.
2577   ObjC and Javascript array and dict literals).
2578
2579   .. code-block:: js
2580
2581      true:                                  false:
2582      var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
2583      f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});
2584
2585 **SpacesInParentheses** (``bool``)
2586   If ``true``, spaces will be inserted after ``(`` and before ``)``.
2587
2588   .. code-block:: c++
2589
2590      true:                                  false:
2591      t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
2592
2593 **SpacesInSquareBrackets** (``bool``)
2594   If ``true``, spaces will be inserted after ``[`` and before ``]``.
2595   Lambdas without arguments or unspecified size array declarations will not
2596   be affected.
2597
2598   .. code-block:: c++
2599
2600      true:                                  false:
2601      int a[ 5 ];                    vs.     int a[5];
2602      std::unique_ptr<int[]> foo() {} // Won't be affected
2603
2604 **Standard** (``LanguageStandard``)
2605   Parse and format C++ constructs compatible with this standard.
2606
2607   .. code-block:: c++
2608
2609      c++03:                                 latest:
2610      vector<set<int> > x;           vs.     vector<set<int>> x;
2611
2612   Possible values:
2613
2614   * ``LS_Cpp03`` (in configuration: ``c++03``)
2615     Parse and format as C++03.
2616     ``Cpp03`` is a deprecated alias for ``c++03``
2617
2618   * ``LS_Cpp11`` (in configuration: ``c++11``)
2619     Parse and format as C++11.
2620
2621   * ``LS_Cpp14`` (in configuration: ``c++14``)
2622     Parse and format as C++14.
2623
2624   * ``LS_Cpp17`` (in configuration: ``c++17``)
2625     Parse and format as C++17.
2626
2627   * ``LS_Cpp20`` (in configuration: ``c++20``)
2628     Parse and format as C++20.
2629
2630   * ``LS_Latest`` (in configuration: ``Latest``)
2631     Parse and format using the latest supported language version.
2632     ``Cpp11`` is a deprecated alias for ``Latest``
2633
2634   * ``LS_Auto`` (in configuration: ``Auto``)
2635     Automatic detection based on the input.
2636
2637
2638
2639 **StatementMacros** (``std::vector<std::string>``)
2640   A vector of macros that should be interpreted as complete
2641   statements.
2642
2643   Typical macros are expressions, and require a semi-colon to be
2644   added; sometimes this is not the case, and this allows to make
2645   clang-format aware of such cases.
2646
2647   For example: Q_UNUSED
2648
2649 **TabWidth** (``unsigned``)
2650   The number of columns used for tab stops.
2651
2652 **TypenameMacros** (``std::vector<std::string>``)
2653   A vector of macros that should be interpreted as type declarations
2654   instead of as function calls.
2655
2656   These are expected to be macros of the form:
2657
2658   .. code-block:: c++
2659
2660     STACK_OF(...)
2661
2662   In the .clang-format configuration file, this can be configured like:
2663
2664   .. code-block:: yaml
2665
2666     TypenameMacros: ['STACK_OF', 'LIST']
2667
2668   For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
2669
2670 **UseCRLF** (``bool``)
2671   Use ``\r\n`` instead of ``\n`` for line breaks.
2672   Also used as fallback if ``DeriveLineEnding`` is true.
2673
2674 **UseTab** (``UseTabStyle``)
2675   The way to use tab characters in the resulting file.
2676
2677   Possible values:
2678
2679   * ``UT_Never`` (in configuration: ``Never``)
2680     Never use tab.
2681
2682   * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
2683     Use tabs only for indentation.
2684
2685   * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
2686     Fill all leading whitespace with tabs, and use spaces for alignment that
2687     appears within a line (e.g. consecutive assignments and declarations).
2688
2689   * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
2690     Use tabs for line continuation and indentation, and spaces for
2691     alignment.
2692
2693   * ``UT_Always`` (in configuration: ``Always``)
2694     Use tabs whenever we need to fill whitespace that spans at least from
2695     one tab stop to the next one.
2696
2697
2698
2699 .. END_FORMAT_STYLE_OPTIONS
2700
2701 Adding additional style options
2702 ===============================
2703
2704 Each additional style option adds costs to the clang-format project. Some of
2705 these costs affect the clang-format development itself, as we need to make
2706 sure that any given combination of options work and that new features don't
2707 break any of the existing options in any way. There are also costs for end users
2708 as options become less discoverable and people have to think about and make a
2709 decision on options they don't really care about.
2710
2711 The goal of the clang-format project is more on the side of supporting a
2712 limited set of styles really well as opposed to supporting every single style
2713 used by a codebase somewhere in the wild. Of course, we do want to support all
2714 major projects and thus have established the following bar for adding style
2715 options. Each new style option must ..
2716
2717   * be used in a project of significant size (have dozens of contributors)
2718   * have a publicly accessible style guide
2719   * have a person willing to contribute and maintain patches
2720
2721 Examples
2722 ========
2723
2724 A style similar to the `Linux Kernel style
2725 <https://www.kernel.org/doc/Documentation/CodingStyle>`_:
2726
2727 .. code-block:: yaml
2728
2729   BasedOnStyle: LLVM
2730   IndentWidth: 8
2731   UseTab: Always
2732   BreakBeforeBraces: Linux
2733   AllowShortIfStatementsOnASingleLine: false
2734   IndentCaseLabels: false
2735
2736 The result is (imagine that tabs are used for indentation here):
2737
2738 .. code-block:: c++
2739
2740   void test()
2741   {
2742           switch (x) {
2743           case 0:
2744           case 1:
2745                   do_something();
2746                   break;
2747           case 2:
2748                   do_something_else();
2749                   break;
2750           default:
2751                   break;
2752           }
2753           if (condition)
2754                   do_something_completely_different();
2755
2756           if (x == y) {
2757                   q();
2758           } else if (x > y) {
2759                   w();
2760           } else {
2761                   r();
2762           }
2763   }
2764
2765 A style similar to the default Visual Studio formatting style:
2766
2767 .. code-block:: yaml
2768
2769   UseTab: Never
2770   IndentWidth: 4
2771   BreakBeforeBraces: Allman
2772   AllowShortIfStatementsOnASingleLine: false
2773   IndentCaseLabels: false
2774   ColumnLimit: 0
2775
2776 The result is:
2777
2778 .. code-block:: c++
2779
2780   void test()
2781   {
2782       switch (suffix)
2783       {
2784       case 0:
2785       case 1:
2786           do_something();
2787           break;
2788       case 2:
2789           do_something_else();
2790           break;
2791       default:
2792           break;
2793       }
2794       if (condition)
2795           do_somthing_completely_different();
2796
2797       if (x == y)
2798       {
2799           q();
2800       }
2801       else if (x > y)
2802       {
2803           w();
2804       }
2805       else
2806       {
2807           r();
2808       }
2809   }