1==========================
2Clang-Format Style Options
3==========================
4
5:doc:`ClangFormatStyleOptions` describes configurable formatting style options
6supported by :doc:`LibFormat` and :doc:`ClangFormat`.
7
8When using :program:`clang-format` command line utility or
9``clang::format::reformat(...)`` functions from code, one can either use one of
10the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
11custom style by configuring specific style options.
12
13
14Configuring Style with clang-format
15===================================
16
17:program:`clang-format` supports two ways to provide custom style options:
18directly specify style configuration in the ``-style=`` command line option or
19use ``-style=file`` and put style configuration in the ``.clang-format`` or
20``_clang-format`` file in the project directory.
21
22When using ``-style=file``, :program:`clang-format` for each input file will
23try to find the ``.clang-format`` file located in the closest parent directory
24of the input file. When the standard input is used, the search is started from
25the current directory.
26
27The ``.clang-format`` file uses YAML format:
28
29.. code-block:: yaml
30
31  key1: value1
32  key2: value2
33  # A comment.
34  ...
35
36The configuration file can consist of several sections each having different
37``Language:`` parameter denoting the programming language this section of the
38configuration is targeted at. See the description of the **Language** option
39below for the list of supported languages. The first section may have no
40language set, it will set the default style options for all lanugages.
41Configuration sections for specific language will override options set in the
42default section.
43
44When :program:`clang-format` formats a file, it auto-detects the language using
45the file name. When formatting standard input or a file that doesn't have the
46extension corresponding to its language, ``-assume-filename=`` option can be
47used to override the file name :program:`clang-format` uses to detect the
48language.
49
50An 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
73An easy way to get a valid ``.clang-format`` file containing all configuration
74options of a certain predefined style is:
75
76.. code-block:: console
77
78  clang-format -style=llvm -dump-config > .clang-format
79
80When specifying configuration in the ``-style=`` option, the same configuration
81is 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
88Disabling Formatting on a Piece of Code
89=======================================
90
91Clang-format understands also special comments that switch formatting in a
92delimited 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
95will 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
106Configuring Style in Code
107=========================
108
109When using ``clang::format::reformat(...)`` functions, the format is specified
110by supplying the `clang::format::FormatStyle
111<http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
112structure.
113
114
115Configurable Format Style Options
116=================================
117
118This section lists the supported style options. Value type is specified for
119each option. For enumeration types possible values are specified both as a C++
120enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
121the 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
549Examples
550========
551
552A 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
564The 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
593A 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
604The 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
639