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) or create a
  11 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
  73 An easy way to get a valid ``.clang-format`` file containing all configuration
  74 options of a certain predefined style is:
  75
  76 .. code-block:: console
  77
  78   clang-format -style=llvm -dump-config > .clang-format
  79
  80 When specifying configuration in the ``-style=`` option, the same configuration
  81 is applied for all input files. The format of the configuration is:
  82
  83 .. code-block:: console
  84
  85   -style='{key1: value1, key2: value2, ...}'
  86
  87
  88 Disabling Formatting on a Piece of Code
  89 =======================================
  90
  91 Clang-format understands also special comments that switch formatting in a
  92 delimited range. The code between a comment ``// clang-format off`` or
  93 ``/* clang-format off */`` up to a comment ``// clang-format on`` or
  94 ``/* clang-format on */`` will not be formatted. The comments themselves
  95 will be formatted (aligned) normally.
  96
  97 .. code-block:: c++
  98
  99   int formatted_code;
 100   // clang-format off
 101       void    unformatted_code  ;
 102   // clang-format on
 103   void formatted_code_again;
 104
 105
 106 Configuring Style in Code
 107 =========================
 108
 109 When using ``clang::format::reformat(...)`` functions, the format is specified
 110 by supplying the `clang::format::FormatStyle
 111 <http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
 112 structure.
 113
 114
 115 Configurable Format Style Options
 116 =================================
 117
 118 This section lists the supported style options. Value type is specified for
 119 each option. For enumeration types possible values are specified both as a C++
 120 enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
 121 the configuration (without a prefix: ``Auto``).
 122
 123
 124 **BasedOnStyle** (``string``)
 125   The style used for all options not specifically set in the configuration.
 126
 127   This option is supported only in the :program:`clang-format` configuration
 128   (both within ``-style='{...}'`` and the ``.clang-format`` file).
 129
 130   Possible values:
 131
 132   * ``LLVM``
 133     A style complying with the `LLVM coding standards
 134     <http://llvm.org/docs/CodingStandards.html>`_
 135   * ``Google``
 136     A style complying with `Google's C++ style guide
 137     <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
 138   * ``Chromium``
 139     A style complying with `Chromium's style guide
 140     <http://www.chromium.org/developers/coding-style>`_
 141   * ``Mozilla``
 142     A style complying with `Mozilla's style guide
 143     <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
 144   * ``WebKit``
 145     A style complying with `WebKit's style guide
 146     <http://www.webkit.org/coding/coding-style.html>`_
 147
 148 .. START_FORMAT_STYLE_OPTIONS
 149
 150 **AccessModifierOffset** (``int``)
 151   The extra indent or outdent of access modifiers, e.g. ``public:``.
 152
 153 **AlignAfterOpenBracket** (``bool``)
 154   If ``true``, horizontally aligns arguments after an open bracket.
 155
 156   This applies to round brackets (parentheses), angle brackets and square
 157   brackets. This will result in formattings like
 158   \code
 159   someLongFunction(argument1,
 160   argument2);
 161   \endcode
 162
 163 **AlignConsecutiveAssignments** (``bool``)
 164   If ``true``, aligns consecutive assignments.
 165
 166   This will align the assignment operators of consecutive lines. This
 167   will result in formattings like
 168   \code
 169   int aaaa = 12;
 170   int b    = 23;
 171   int ccc  = 23;
 172   \endcode
 173
 174 **AlignEscapedNewlinesLeft** (``bool``)
 175   If ``true``, aligns escaped newlines as far left as possible.
 176   Otherwise puts them into the right-most column.
 177
 178 **AlignOperands** (``bool``)
 179   If ``true``, horizontally align operands of binary and ternary
 180   expressions.
 181
 182 **AlignTrailingComments** (``bool``)
 183   If ``true``, aligns trailing comments.
 184
 185 **AllowAllParametersOfDeclarationOnNextLine** (``bool``)
 186   Allow putting all parameters of a function declaration onto
 187   the next line even if ``BinPackParameters`` is ``false``.
 188
 189 **AllowShortBlocksOnASingleLine** (``bool``)
 190   Allows contracting simple braced statements to a single line.
 191
 192   E.g., this allows ``if (a) { return; }`` to be put on a single line.
 193
 194 **AllowShortCaseLabelsOnASingleLine** (``bool``)
 195   If ``true``, short case labels will be contracted to a single line.
 196
 197 **AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``)
 198   Dependent on the value, ``int f() { return 0; }`` can be put
 199   on a single line.
 200
 201   Possible values:
 202
 203   * ``SFS_None`` (in configuration: ``None``)
 204     Never merge functions into a single line.
 205   * ``SFS_Empty`` (in configuration: ``Empty``)
 206     Only merge empty functions.
 207   * ``SFS_Inline`` (in configuration: ``Inline``)
 208     Only merge functions defined inside a class. Implies "empty".
 209   * ``SFS_All`` (in configuration: ``All``)
 210     Merge all functions fitting on a single line.
 211
 212
 213 **AllowShortIfStatementsOnASingleLine** (``bool``)
 214   If ``true``, ``if (a) return;`` can be put on a single
 215   line.
 216
 217 **AllowShortLoopsOnASingleLine** (``bool``)
 218   If ``true``, ``while (true) continue;`` can be put on a
 219   single line.
 220
 221 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
 222   The function definition return type breaking style to use.
 223
 224   Possible values:
 225
 226   * ``DRTBS_None`` (in configuration: ``None``)
 227     Break after return type automatically.
 228     ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
 229   * ``DRTBS_All`` (in configuration: ``All``)
 230     Always break after the return type.
 231   * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
 232     Always break after the return types of top level functions.
 233
 234
 235 **AlwaysBreakBeforeMultilineStrings** (``bool``)
 236   If ``true``, always break before multiline string literals.
 237
 238   This flag is mean to make cases where there are multiple multiline strings
 239   in a file look more consistent. Thus, it will only take effect if wrapping
 240   the string at that point leads to it being indented
 241   ``ContinuationIndentWidth`` spaces from the start of the line.
 242
 243 **AlwaysBreakTemplateDeclarations** (``bool``)
 244   If ``true``, always break after the ``template<...>`` of a
 245   template declaration.
 246
 247 **BinPackArguments** (``bool``)
 248   If ``false``, a function call's arguments will either be all on the
 249   same line or will have one line each.
 250
 251 **BinPackParameters** (``bool``)
 252   If ``false``, a function declaration's or function definition's
 253   parameters will either all be on the same line or will have one line each.
 254
 255 **BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
 256   The way to wrap binary operators.
 257
 258   Possible values:
 259
 260   * ``BOS_None`` (in configuration: ``None``)
 261     Break after operators.
 262   * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
 263     Break before operators that aren't assignments.
 264   * ``BOS_All`` (in configuration: ``All``)
 265     Break before operators.
 266
 267
 268 **BreakBeforeBraces** (``BraceBreakingStyle``)
 269   The brace breaking style to use.
 270
 271   Possible values:
 272
 273   * ``BS_Attach`` (in configuration: ``Attach``)
 274     Always attach braces to surrounding context.
 275   * ``BS_Linux`` (in configuration: ``Linux``)
 276     Like ``Attach``, but break before braces on function, namespace and
 277     class definitions.
 278   * ``BS_Mozilla`` (in configuration: ``Mozilla``)
 279     Like ``Attach``, but break before braces on enum, function, and record
 280     definitions.
 281   * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
 282     Like ``Attach``, but break before function definitions, and 'else'.
 283   * ``BS_Allman`` (in configuration: ``Allman``)
 284     Always break before braces.
 285   * ``BS_GNU`` (in configuration: ``GNU``)
 286     Always break before braces and add an extra level of indentation to
 287     braces of control statements, not to those of class, function
 288     or other definitions.
 289
 290
 291 **BreakBeforeTernaryOperators** (``bool``)
 292   If ``true``, ternary operators will be placed after line breaks.
 293
 294 **BreakConstructorInitializersBeforeComma** (``bool``)
 295   Always break constructor initializers before commas and align
 296   the commas with the colon.
 297
 298 **ColumnLimit** (``unsigned``)
 299   The column limit.
 300
 301   A column limit of ``0`` means that there is no column limit. In this case,
 302   clang-format will respect the input's line breaking decisions within
 303   statements unless they contradict other rules.
 304
 305 **CommentPragmas** (``std::string``)
 306   A regular expression that describes comments with special meaning,
 307   which should not be split into lines or otherwise changed.
 308
 309 **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
 310   If the constructor initializers don't fit on a line, put each
 311   initializer on its own line.
 312
 313 **ConstructorInitializerIndentWidth** (``unsigned``)
 314   The number of characters to use for indentation of constructor
 315   initializer lists.
 316
 317 **ContinuationIndentWidth** (``unsigned``)
 318   Indent width for line continuations.
 319
 320 **Cpp11BracedListStyle** (``bool``)
 321   If ``true``, format braced lists as best suited for C++11 braced
 322   lists.
 323
 324   Important differences:
 325   - No spaces inside the braced list.
 326   - No line break before the closing brace.
 327   - Indentation with the continuation indent, not with the block indent.
 328
 329   Fundamentally, C++11 braced lists are formatted exactly like function
 330   calls would be formatted in their place. If the braced list follows a name
 331   (e.g. a type or variable name), clang-format formats as if the ``{}`` were
 332   the parentheses of a function call with that name. If there is no name,
 333   a zero-length name is assumed.
 334
 335 **DerivePointerAlignment** (``bool``)
 336   If ``true``, analyze the formatted file for the most common
 337   alignment of & and \*. ``PointerAlignment`` is then used only as fallback.
 338
 339 **DisableFormat** (``bool``)
 340   Disables formatting completely.
 341
 342 **ExperimentalAutoDetectBinPacking** (``bool``)
 343   If ``true``, clang-format detects whether function calls and
 344   definitions are formatted with one parameter per line.
 345
 346   Each call can be bin-packed, one-per-line or inconclusive. If it is
 347   inconclusive, e.g. completely on one line, but a decision needs to be
 348   made, clang-format analyzes whether there are other bin-packed cases in
 349   the input file and act accordingly.
 350
 351   NOTE: This is an experimental flag, that might go away or be renamed. Do
 352   not use this in config files, etc. Use at your own risk.
 353
 354 **ForEachMacros** (``std::vector<std::string>``)
 355   A vector of macros that should be interpreted as foreach loops
 356   instead of as function calls.
 357
 358   These are expected to be macros of the form:
 359   \code
 360   FOREACH(<variable-declaration>, ...)
 361   <loop-body>
 362   \endcode
 363
 364   For example: BOOST_FOREACH.
 365
 366 **IndentCaseLabels** (``bool``)
 367   Indent case labels one level from the switch statement.
 368
 369   When ``false``, use the same indentation level as for the switch statement.
 370   Switch statement body is always indented one level more than case labels.
 371
 372 **IndentWidth** (``unsigned``)
 373   The number of columns to use for indentation.
 374
 375 **IndentWrappedFunctionNames** (``bool``)
 376   Indent if a function definition or declaration is wrapped after the
 377   type.
 378
 379 **KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
 380   If true, empty lines at the start of blocks are kept.
 381
 382 **Language** (``LanguageKind``)
 383   Language, this format style is targeted at.
 384
 385   Possible values:
 386
 387   * ``LK_None`` (in configuration: ``None``)
 388     Do not use.
 389   * ``LK_Cpp`` (in configuration: ``Cpp``)
 390     Should be used for C, C++, ObjectiveC, ObjectiveC++.
 391   * ``LK_Java`` (in configuration: ``Java``)
 392     Should be used for Java.
 393   * ``LK_JavaScript`` (in configuration: ``JavaScript``)
 394     Should be used for JavaScript.
 395   * ``LK_Proto`` (in configuration: ``Proto``)
 396     Should be used for Protocol Buffers
 397     (https://developers.google.com/protocol-buffers/).
 398
 399
 400 **MacroBlockBegin** (``std::string``)
 401   A regular expression matching macros that start a block.
 402
 403 **MacroBlockEnd** (``std::string``)
 404   A regular expression matching macros that end a block.
 405
 406 **MaxEmptyLinesToKeep** (``unsigned``)
 407   The maximum number of consecutive empty lines to keep.
 408
 409 **NamespaceIndentation** (``NamespaceIndentationKind``)
 410   The indentation used for namespaces.
 411
 412   Possible values:
 413
 414   * ``NI_None`` (in configuration: ``None``)
 415     Don't indent in namespaces.
 416   * ``NI_Inner`` (in configuration: ``Inner``)
 417     Indent only in inner namespaces (nested in other namespaces).
 418   * ``NI_All`` (in configuration: ``All``)
 419     Indent in all namespaces.
 420
 421
 422 **ObjCBlockIndentWidth** (``unsigned``)
 423   The number of characters to use for indentation of ObjC blocks.
 424
 425 **ObjCSpaceAfterProperty** (``bool``)
 426   Add a space after ``@property`` in Objective-C, i.e. use
 427   ``\@property (readonly)`` instead of ``\@property(readonly)``.
 428
 429 **ObjCSpaceBeforeProtocolList** (``bool``)
 430   Add a space in front of an Objective-C protocol list, i.e. use
 431   ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
 432
 433 **PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
 434   The penalty for breaking a function call after "call(".
 435
 436 **PenaltyBreakComment** (``unsigned``)
 437   The penalty for each line break introduced inside a comment.
 438
 439 **PenaltyBreakFirstLessLess** (``unsigned``)
 440   The penalty for breaking before the first ``<<``.
 441
 442 **PenaltyBreakString** (``unsigned``)
 443   The penalty for each line break introduced inside a string literal.
 444
 445 **PenaltyExcessCharacter** (``unsigned``)
 446   The penalty for each character outside of the column limit.
 447
 448 **PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
 449   Penalty for putting the return type of a function onto its own
 450   line.
 451
 452 **PointerAlignment** (``PointerAlignmentStyle``)
 453   Pointer and reference alignment style.
 454
 455   Possible values:
 456
 457   * ``PAS_Left`` (in configuration: ``Left``)
 458     Align pointer to the left.
 459   * ``PAS_Right`` (in configuration: ``Right``)
 460     Align pointer to the right.
 461   * ``PAS_Middle`` (in configuration: ``Middle``)
 462     Align pointer in the middle.
 463
 464
 465 **SpaceAfterCStyleCast** (``bool``)
 466   If ``true``, a space may be inserted after C style casts.
 467
 468 **SpaceBeforeAssignmentOperators** (``bool``)
 469   If ``false``, spaces will be removed before assignment operators.
 470
 471 **SpaceBeforeParens** (``SpaceBeforeParensOptions``)
 472   Defines in which cases to put a space before opening parentheses.
 473
 474   Possible values:
 475
 476   * ``SBPO_Never`` (in configuration: ``Never``)
 477     Never put a space before opening parentheses.
 478   * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
 479     Put a space before opening parentheses only after control statement
 480     keywords (``for/if/while...``).
 481   * ``SBPO_Always`` (in configuration: ``Always``)
 482     Always put a space before opening parentheses, except when it's
 483     prohibited by the syntax rules (in function-like macro definitions) or
 484     when determined by other style rules (after unary operators, opening
 485     parentheses, etc.)
 486
 487
 488 **SpaceInEmptyParentheses** (``bool``)
 489   If ``true``, spaces may be inserted into '()'.
 490
 491 **SpacesBeforeTrailingComments** (``unsigned``)
 492   The number of spaces before trailing line comments
 493   (``//`` - comments).
 494
 495   This does not affect trailing block comments (``/**/`` - comments) as those
 496   commonly have different usage patterns and a number of special cases.
 497
 498 **SpacesInAngles** (``bool``)
 499   If ``true``, spaces will be inserted after '<' and before '>' in
 500   template argument lists
 501
 502 **SpacesInCStyleCastParentheses** (``bool``)
 503   If ``true``, spaces may be inserted into C style casts.
 504
 505 **SpacesInContainerLiterals** (``bool``)
 506   If ``true``, spaces are inserted inside container literals (e.g.
 507   ObjC and Javascript array and dict literals).
 508
 509 **SpacesInParentheses** (``bool``)
 510   If ``true``, spaces will be inserted after '(' and before ')'.
 511
 512 **SpacesInSquareBrackets** (``bool``)
 513   If ``true``, spaces will be inserted after '[' and before ']'.
 514
 515 **Standard** (``LanguageStandard``)
 516   Format compatible with this standard, e.g. use
 517   ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03.
 518
 519   Possible values:
 520
 521   * ``LS_Cpp03`` (in configuration: ``Cpp03``)
 522     Use C++03-compatible syntax.
 523   * ``LS_Cpp11`` (in configuration: ``Cpp11``)
 524     Use features of C++11 (e.g. ``A<A<int>>`` instead of
 525     ``A<A<int> >``).
 526   * ``LS_Auto`` (in configuration: ``Auto``)
 527     Automatic detection based on the input.
 528
 529
 530 **TabWidth** (``unsigned``)
 531   The number of columns used for tab stops.
 532
 533 **UseTab** (``UseTabStyle``)
 534   The way to use tab characters in the resulting file.
 535
 536   Possible values:
 537
 538   * ``UT_Never`` (in configuration: ``Never``)
 539     Never use tab.
 540   * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
 541     Use tabs only for indentation.
 542   * ``UT_Always`` (in configuration: ``Always``)
 543     Use tabs whenever we need to fill whitespace that spans at least from
 544     one tab stop to the next one.
 545
 546
 547 .. END_FORMAT_STYLE_OPTIONS
 548
 549 Examples
 550 ========
 551
 552 A style similar to the `Linux Kernel style
 553 <https://www.kernel.org/doc/Documentation/CodingStyle>`_:
 554
 555 .. code-block:: yaml
 556
 557   BasedOnStyle: LLVM
 558   IndentWidth: 8
 559   UseTab: Always
 560   BreakBeforeBraces: Linux
 561   AllowShortIfStatementsOnASingleLine: false
 562   IndentCaseLabels: false
 563
 564 The result is (imagine that tabs are used for indentation here):
 565
 566 .. code-block:: c++
 567
 568   void test()
 569   {
 570           switch (x) {
 571           case 0:
 572           case 1:
 573                   do_something();
 574                   break;
 575           case 2:
 576                   do_something_else();
 577                   break;
 578           default:
 579                   break;
 580           }
 581           if (condition)
 582                   do_something_completely_different();
 583
 584           if (x == y) {
 585                   q();
 586           } else if (x > y) {
 587                   w();
 588           } else {
 589                   r();
 590           }
 591   }
 592
 593 A style similar to the default Visual Studio formatting style:
 594
 595 .. code-block:: yaml
 596
 597   UseTab: Never
 598   IndentWidth: 4
 599   BreakBeforeBraces: Allman
 600   AllowShortIfStatementsOnASingleLine: false
 601   IndentCaseLabels: false
 602   ColumnLimit: 0
 603
 604 The result is:
 605
 606 .. code-block:: c++
 607
 608   void test()
 609   {
 610       switch (suffix)
 611       {
 612       case 0:
 613       case 1:
 614           do_something();
 615           break;
 616       case 2:
 617           do_something_else();
 618           break;
 619       default:
 620           break;
 621       }
 622       if (condition)
 623           do_somthing_completely_different();
 624
 625       if (x == y)
 626       {
 627           q();
 628       }
 629       else if (x > y)
 630       {
 631           w();
 632       }
 633       else
 634       {
 635           r();
 636       }
 637   }
 638