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** (``bool``)
110  If ``true``, ``int f() { return 0; }`` can be put on a single
111  line.
112
113**AllowShortIfStatementsOnASingleLine** (``bool``)
114  If ``true``, ``if (a) return;`` can be put on a single
115  line.
116
117**AllowShortLoopsOnASingleLine** (``bool``)
118  If ``true``, ``while (true) continue;`` can be put on a
119  single line.
120
121**AlwaysBreakBeforeMultilineStrings** (``bool``)
122  If ``true``, always break before multiline string literals.
123
124**AlwaysBreakTemplateDeclarations** (``bool``)
125  If ``true``, always break after the ``template<...>`` of a
126  template declaration.
127
128**BinPackParameters** (``bool``)
129  If ``false``, a function call's or function definition's parameters
130  will either all be on the same line or will have one line each.
131
132**BreakBeforeBinaryOperators** (``bool``)
133  If ``true``, binary operators will be placed after line breaks.
134
135**BreakBeforeBraces** (``BraceBreakingStyle``)
136  The brace breaking style to use.
137
138  Possible values:
139
140  * ``BS_Attach`` (in configuration: ``Attach``)
141    Always attach braces to surrounding context.
142  * ``BS_Linux`` (in configuration: ``Linux``)
143    Like ``Attach``, but break before braces on function, namespace and
144    class definitions.
145  * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
146    Like ``Attach``, but break before function definitions.
147  * ``BS_Allman`` (in configuration: ``Allman``)
148    Always break before braces.
149  * ``BS_GNU`` (in configuration: ``GNU``)
150    Always break before braces and add an extra level of indentation to
151    braces of control statements, not to those of class, function
152    or other definitions.
153
154
155**BreakBeforeTernaryOperators** (``bool``)
156  If ``true``, ternary operators will be placed after line breaks.
157
158**BreakConstructorInitializersBeforeComma** (``bool``)
159  Always break constructor initializers before commas and align
160  the commas with the colon.
161
162**ColumnLimit** (``unsigned``)
163  The column limit.
164
165  A column limit of ``0`` means that there is no column limit. In this case,
166  clang-format will respect the input's line breaking decisions within
167  statements unless they contradict other rules.
168
169**CommentPragmas** (``std::string``)
170  A regular expression that describes comments with special meaning,
171  which should not be split into lines or otherwise changed.
172
173**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
174  If the constructor initializers don't fit on a line, put each
175  initializer on its own line.
176
177**ConstructorInitializerIndentWidth** (``unsigned``)
178  The number of characters to use for indentation of constructor
179  initializer lists.
180
181**ContinuationIndentWidth** (``unsigned``)
182  Indent width for line continuations.
183
184**Cpp11BracedListStyle** (``bool``)
185  If ``true``, format braced lists as best suited for C++11 braced
186  lists.
187
188  Important differences:
189  - No spaces inside the braced list.
190  - No line break before the closing brace.
191  - Indentation with the continuation indent, not with the block indent.
192
193  Fundamentally, C++11 braced lists are formatted exactly like function
194  calls would be formatted in their place. If the braced list follows a name
195  (e.g. a type or variable name), clang-format formats as if the ``{}`` were
196  the parentheses of a function call with that name. If there is no name,
197  a zero-length name is assumed.
198
199**DerivePointerBinding** (``bool``)
200  If ``true``, analyze the formatted file for the most common binding
201  and use ``PointerBindsToType`` only as fallback.
202
203**ExperimentalAutoDetectBinPacking** (``bool``)
204  If ``true``, clang-format detects whether function calls and
205  definitions are formatted with one parameter per line.
206
207  Each call can be bin-packed, one-per-line or inconclusive. If it is
208  inconclusive, e.g. completely on one line, but a decision needs to be
209  made, clang-format analyzes whether there are other bin-packed cases in
210  the input file and act accordingly.
211
212  NOTE: This is an experimental flag, that might go away or be renamed. Do
213  not use this in config files, etc. Use at your own risk.
214
215**IndentCaseLabels** (``bool``)
216  Indent case labels one level from the switch statement.
217
218  When ``false``, use the same indentation level as for the switch statement.
219  Switch statement body is always indented one level more than case labels.
220
221**IndentFunctionDeclarationAfterType** (``bool``)
222  If ``true``, indent when breaking function declarations which
223  are not also definitions after the type.
224
225**IndentWidth** (``unsigned``)
226  The number of columns to use for indentation.
227
228**Language** (``LanguageKind``)
229  Language, this format style is targeted at.
230
231  Possible values:
232
233  * ``LK_None`` (in configuration: ``None``)
234    Do not use.
235  * ``LK_Cpp`` (in configuration: ``Cpp``)
236    Should be used for C, C++, ObjectiveC, ObjectiveC++.
237  * ``LK_JavaScript`` (in configuration: ``JavaScript``)
238    Should be used for JavaScript.
239  * ``LK_Proto`` (in configuration: ``Proto``)
240    Should be used for Protocol Buffers
241    (https://developers.google.com/protocol-buffers/).
242
243
244**MaxEmptyLinesToKeep** (``unsigned``)
245  The maximum number of consecutive empty lines to keep.
246
247**NamespaceIndentation** (``NamespaceIndentationKind``)
248  The indentation used for namespaces.
249
250  Possible values:
251
252  * ``NI_None`` (in configuration: ``None``)
253    Don't indent in namespaces.
254  * ``NI_Inner`` (in configuration: ``Inner``)
255    Indent only in inner namespaces (nested in other namespaces).
256  * ``NI_All`` (in configuration: ``All``)
257    Indent in all namespaces.
258
259
260**ObjCSpaceAfterProperty** (``bool``)
261  Add a space after ``@property`` in Objective-C, i.e. use
262  ``@property (readonly)`` instead of ``@property(readonly)``.
263
264**ObjCSpaceBeforeProtocolList** (``bool``)
265  Add a space in front of an Objective-C protocol list, i.e. use
266  ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
267
268**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
269  The penalty for breaking a function call after "call(".
270
271**PenaltyBreakComment** (``unsigned``)
272  The penalty for each line break introduced inside a comment.
273
274**PenaltyBreakFirstLessLess** (``unsigned``)
275  The penalty for breaking before the first ``<<``.
276
277**PenaltyBreakString** (``unsigned``)
278  The penalty for each line break introduced inside a string literal.
279
280**PenaltyExcessCharacter** (``unsigned``)
281  The penalty for each character outside of the column limit.
282
283**PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
284  Penalty for putting the return type of a function onto its own
285  line.
286
287**PointerBindsToType** (``bool``)
288  Set whether & and * bind to the type as opposed to the variable.
289
290**SpaceBeforeAssignmentOperators** (``bool``)
291  If ``false``, spaces will be removed before assignment operators.
292
293**SpaceBeforeParens** (``SpaceBeforeParensOptions``)
294  Defines in which cases to put a space before opening parentheses.
295
296  Possible values:
297
298  * ``SBPO_Never`` (in configuration: ``Never``)
299    Never put a space before opening parentheses.
300  * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
301    Put a space before opening parentheses only after control statement
302    keywords (``for/if/while...``).
303  * ``SBPO_Always`` (in configuration: ``Always``)
304    Always put a space before opening parentheses, except when it's
305    prohibited by the syntax rules (in function-like macro definitions) or
306    when determined by other style rules (after unary operators, opening
307    parentheses, etc.)
308
309
310**SpaceInEmptyParentheses** (``bool``)
311  If ``true``, spaces may be inserted into '()'.
312
313**SpacesBeforeTrailingComments** (``unsigned``)
314  The number of spaces to before trailing line comments.
315
316**SpacesInAngles** (``bool``)
317  If ``true``, spaces will be inserted after '<' and before '>' in
318  template argument lists
319
320**SpacesInCStyleCastParentheses** (``bool``)
321  If ``true``, spaces may be inserted into C style casts.
322
323**SpacesInContainerLiterals** (``bool``)
324  If ``true``, spaces are inserted inside container literals (e.g.
325  ObjC and Javascript array and dict literals).
326
327**SpacesInParentheses** (``bool``)
328  If ``true``, spaces will be inserted after '(' and before ')'.
329
330**Standard** (``LanguageStandard``)
331  Format compatible with this standard, e.g. use
332  ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03.
333
334  Possible values:
335
336  * ``LS_Cpp03`` (in configuration: ``Cpp03``)
337    Use C++03-compatible syntax.
338  * ``LS_Cpp11`` (in configuration: ``Cpp11``)
339    Use features of C++11 (e.g. ``A<A<int>>`` instead of
340    ``A<A<int> >``).
341  * ``LS_Auto`` (in configuration: ``Auto``)
342    Automatic detection based on the input.
343
344
345**TabWidth** (``unsigned``)
346  The number of columns used for tab stops.
347
348**UseTab** (``UseTabStyle``)
349  The way to use tab characters in the resulting file.
350
351  Possible values:
352
353  * ``UT_Never`` (in configuration: ``Never``)
354    Never use tab.
355  * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
356    Use tabs only for indentation.
357  * ``UT_Always`` (in configuration: ``Always``)
358    Use tabs whenever we need to fill whitespace that spans at least from
359    one tab stop to the next one.
360
361
362.. END_FORMAT_STYLE_OPTIONS
363
364Examples
365========
366
367A style similar to the `Linux Kernel style
368<https://www.kernel.org/doc/Documentation/CodingStyle>`_:
369
370.. code-block:: yaml
371
372  BasedOnStyle: LLVM
373  IndentWidth: 8
374  UseTab: Always
375  BreakBeforeBraces: Linux
376  AllowShortIfStatementsOnASingleLine: false
377  IndentCaseLabels: false
378
379The result is (imagine that tabs are used for indentation here):
380
381.. code-block:: c++
382
383  void test()
384  {
385          switch (x) {
386          case 0:
387          case 1:
388                  do_something();
389                  break;
390          case 2:
391                  do_something_else();
392                  break;
393          default:
394                  break;
395          }
396          if (condition)
397                  do_something_completely_different();
398
399          if (x == y) {
400                  q();
401          } else if (x > y) {
402                  w();
403          } else {
404                  r();
405          }
406  }
407
408A style similar to the default Visual Studio formatting style:
409
410.. code-block:: yaml
411
412  UseTab: Never
413  IndentWidth: 4
414  BreakBeforeBraces: Allman
415  AllowShortIfStatementsOnASingleLine: false
416  IndentCaseLabels: false
417  ColumnLimit: 0
418
419The result is:
420
421.. code-block:: c++
422
423  void test()
424  {
425      switch (suffix)
426      {
427      case 0:
428      case 1:
429          do_something();
430          break;
431      case 2:
432          do_something_else();
433          break;
434      default:
435          break;
436      }
437      if (condition)
438          do_somthing_completely_different();
439
440      if (x == y)
441      {
442          q();
443      }
444      else if (x > y)
445      {
446          w();
447      }
448      else
449      {
450          r();
451      }
452  }
453
454