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