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