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