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