ClangFormatStyleOptions.rst source code [clang_source_code/docs/ClangFormatStyleOptions.rst]

1	==========================
2	Clang-Format Style Options
3	==========================
4
5	:doc:`ClangFormatStyleOptions` describes configurable formatting style options
6	supported by :doc:`LibFormat` and :doc:`ClangFormat`.
7
8	When using :program:`clang-format` command line utility or
9	``clang::format::reformat(...)`` functions from code, one can either use one of
10	the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft) or
11	create a custom style by configuring specific style options.
12
13
14	Configuring Style with clang-format
15	===================================
16
17	:program:`clang-format` supports two ways to provide custom style options:
18	directly specify style configuration in the ``-style=`` command line option or
19	use ``-style=file`` and put style configuration in the ``.clang-format`` or
20	``_clang-format`` file in the project directory.
21
22	When using ``-style=file``, :program:`clang-format` for each input file will
23	try to find the ``.clang-format`` file located in the closest parent directory
24	of the input file. When the standard input is used, the search is started from
25	the current directory.
26
27	The ``.clang-format`` file uses YAML format:
28
29	.. code-block:: yaml
30
31	key1: value1
32	key2: value2
33	# A comment.
34	...
35
36	The configuration file can consist of several sections each having different
37	``Language:`` parameter denoting the programming language this section of the
38	configuration is targeted at. See the description of the Language option
39	below for the list of supported languages. The first section may have no
40	language set, it will set the default style options for all lanugages.
41	Configuration sections for specific language will override options set in the
42	default section.
43
44	When :program:`clang-format` formats a file, it auto-detects the language using
45	the file name. When formatting standard input or a file that doesn't have the
46	extension corresponding to its language, ``-assume-filename=`` option can be
47	used to override the file name :program:`clang-format` uses to detect the
48	language.
49
50	An 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	Language: CSharp
73	# Use 100 columns for C#.
74	ColumnLimit: 100
75	...
76
77	An easy way to get a valid ``.clang-format`` file containing all configuration
78	options of a certain predefined style is:
79
80	.. code-block:: console
81
82	clang-format -style=llvm -dump-config > .clang-format
83
84	When specifying configuration in the ``-style=`` option, the same configuration
85	is applied for all input files. The format of the configuration is:
86
87	.. code-block:: console
88
89	-style='{key1: value1, key2: value2, ...}'
90
91
92	Disabling Formatting on a Piece of Code
93	=======================================
94
95	Clang-format understands also special comments that switch formatting in a
96	delimited range. The code between a comment ``// clang-format off`` or
97	``/* clang-format off */`` up to a comment ``// clang-format on`` or
98	``/* clang-format on */`` will not be formatted. The comments themselves
99	will be formatted (aligned) normally.
100
101	.. code-block:: c++
102
103	int formatted_code;
104	// clang-format off
105	void unformatted_code ;
106	// clang-format on
107	void formatted_code_again;
108
109
110	Configuring Style in Code
111	=========================
112
113	When using ``clang::format::reformat(...)`` functions, the format is specified
114	by supplying the `clang::format::FormatStyle
115	<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
116	structure.
117
118
119	Configurable Format Style Options
120	=================================
121
122	This section lists the supported style options. Value type is specified for
123	each option. For enumeration types possible values are specified both as a C++
124	enumeration member (with a prefix, e.g. ``LS_Auto``), and as a value usable in
125	the configuration (without a prefix: ``Auto``).
126
127
128	BasedOnStyle (``string``)
129	The style used for all options not specifically set in the configuration.
130
131	This option is supported only in the :program:`clang-format` configuration
132	(both within ``-style='{...}'`` and the ``.clang-format`` file).
133
134	Possible values:
135
136	* ``LLVM``
137	A style complying with the `LLVM coding standards
138	<https://llvm.org/docs/CodingStandards.html>`_
139	* ``Google``
140	A style complying with `Google's C++ style guide
141	<http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
142	* ``Chromium``
143	A style complying with `Chromium's style guide
144	<https://www.chromium.org/developers/coding-style>`_
145	* ``Mozilla``
146	A style complying with `Mozilla's style guide
147	<https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
148	* ``WebKit``
149	A style complying with `WebKit's style guide
150	<https://www.webkit.org/coding/coding-style.html>`_
151	* ``Microsoft``
152	A style complying with `Microsoft's style guide
153	<https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017>`_
154
155	.. START_FORMAT_STYLE_OPTIONS
156
157	AccessModifierOffset (``int``)
158	The extra indent or outdent of access modifiers, e.g. ``public:``.
159
160	AlignAfterOpenBracket (``BracketAlignmentStyle``)
161	If ``true``, horizontally aligns arguments after an open bracket.
162
163	This applies to round brackets (parentheses), angle brackets and square
164	brackets.
165
166	Possible values:
167
168	* ``BAS_Align`` (in configuration: ``Align``)
169	Align parameters on the open bracket, e.g.:
170
171	.. code-block:: c++
172
173	someLongFunction(argument1,
174	argument2);
175
176	* ``BAS_DontAlign`` (in configuration: ``DontAlign``)
177	Don't align, instead use ``ContinuationIndentWidth``, e.g.:
178
179	.. code-block:: c++
180
181	someLongFunction(argument1,
182	argument2);
183
184	* ``BAS_AlwaysBreak`` (in configuration: ``AlwaysBreak``)
185	Always break after an open bracket, if the parameters don't fit
186	on a single line, e.g.:
187
188	.. code-block:: c++
189
190	someLongFunction(
191	argument1, argument2);
192
193
194
195	AlignConsecutiveAssignments (``bool``)
196	If ``true``, aligns consecutive assignments.
197
198	This will align the assignment operators of consecutive lines. This
199	will result in formattings like
200
201	.. code-block:: c++
202
203	int aaaa = 12;
204	int b = 23;
205	int ccc = 23;
206
207	AlignConsecutiveDeclarations (``bool``)
208	If ``true``, aligns consecutive declarations.
209
210	This will align the declaration names of consecutive lines. This
211	will result in formattings like
212
213	.. code-block:: c++
214
215	int aaaa = 12;
216	float b = 23;
217	std::string ccc = 23;
218
219	AlignEscapedNewlines (``EscapedNewlineAlignmentStyle``)
220	Options for aligning backslashes in escaped newlines.
221
222	Possible values:
223
224	* ``ENAS_DontAlign`` (in configuration: ``DontAlign``)
225	Don't align escaped newlines.
226
227	.. code-block:: c++
228
229	#define A \
230	int aaaa; \
231	int b; \
232	int dddddddddd;
233
234	* ``ENAS_Left`` (in configuration: ``Left``)
235	Align escaped newlines as far left as possible.
236
237	.. code-block:: c++
238
239	true:
240	#define A \
241	int aaaa; \
242	int b; \
243	int dddddddddd;
244
245	false:
246
247	* ``ENAS_Right`` (in configuration: ``Right``)
248	Align escaped newlines in the right-most column.
249
250	.. code-block:: c++
251
252	#define A \
253	int aaaa; \
254	int b; \
255	int dddddddddd;
256
257
258
259	AlignOperands (``bool``)
260	If ``true``, horizontally align operands of binary and ternary
261	expressions.
262
263	Specifically, this aligns operands of a single expression that needs to be
264	split over multiple lines, e.g.:
265
266	.. code-block:: c++
267
268	int aaa = bbbbbbbbbbbbbbb +
269	ccccccccccccccc;
270
271	AlignTrailingComments (``bool``)
272	If ``true``, aligns trailing comments.
273
274	.. code-block:: c++
275
276	true: false:
277	int a; // My comment a vs. int a; // My comment a
278	int b = 2; // comment b int b = 2; // comment about b
279
280	AllowAllArgumentsOnNextLine (``bool``)
281	If a function call or braced initializer list doesn't fit on a
282	line, allow putting all arguments onto the next line, even if
283	``BinPackArguments`` is ``false``.
284
285	.. code-block:: c++
286
287	true:
288	callFunction(
289	a, b, c, d);
290
291	false:
292	callFunction(a,
293	b,
294	c,
295	d);
296
297	AllowAllConstructorInitializersOnNextLine (``bool``)
298	If a constructor definition with a member initializer list doesn't
299	fit on a single line, allow putting all member initializers onto the next
300	line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true.
301	Note that this parameter has no effect if
302	```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false.
303
304	.. code-block:: c++
305
306	true:
307	MyClass::MyClass() :
308	member0(0), member1(2) {}
309
310	false:
311	MyClass::MyClass() :
312	member0(0),
313	member1(2) {}
314
315	AllowAllParametersOfDeclarationOnNextLine (``bool``)
316	If the function declaration doesn't fit on a line,
317	allow putting all parameters of a function declaration onto
318	the next line even if ``BinPackParameters`` is ``false``.
319
320	.. code-block:: c++
321
322	true:
323	void myFunction(
324	int a, int b, int c, int d, int e);
325
326	false:
327	void myFunction(int a,
328	int b,
329	int c,
330	int d,
331	int e);
332
333	AllowShortBlocksOnASingleLine (``bool``)
334	Allows contracting simple braced statements to a single line.
335
336	E.g., this allows ``if (a) { return; }`` to be put on a single line.
337
338	AllowShortCaseLabelsOnASingleLine (``bool``)
339	If ``true``, short case labels will be contracted to a single line.
340
341	.. code-block:: c++
342
343	true: false:
344	switch (a) { vs. switch (a) {
345	case 1: x = 1; break; case 1:
346	case 2: return; x = 1;
347	} break;
348	case 2:
349	return;
350	}
351
352	AllowShortFunctionsOnASingleLine (``ShortFunctionStyle``)
353	Dependent on the value, ``int f() { return 0; }`` can be put on a
354	single line.
355
356	Possible values:
357
358	* ``SFS_None`` (in configuration: ``None``)
359	Never merge functions into a single line.
360
361	* ``SFS_InlineOnly`` (in configuration: ``InlineOnly``)
362	Only merge functions defined inside a class. Same as "inline",
363	except it does not implies "empty": i.e. top level empty functions
364	are not merged either.
365
366	.. code-block:: c++
367
368	class Foo {
369	void f() { foo(); }
370	};
371	void f() {
372	foo();
373	}
374	void f() {
375	}
376
377	* ``SFS_Empty`` (in configuration: ``Empty``)
378	Only merge empty functions.
379
380	.. code-block:: c++
381
382	void f() {}
383	void f2() {
384	bar2();
385	}
386
387	* ``SFS_Inline`` (in configuration: ``Inline``)
388	Only merge functions defined inside a class. Implies "empty".
389
390	.. code-block:: c++
391
392	class Foo {
393	void f() { foo(); }
394	};
395	void f() {
396	foo();
397	}
398	void f() {}
399
400	* ``SFS_All`` (in configuration: ``All``)
401	Merge all functions fitting on a single line.
402
403	.. code-block:: c++
404
405	class Foo {
406	void f() { foo(); }
407	};
408	void f() { bar(); }
409
410	AllowShortIfStatementsOnASingleLine (``ShortIfStyle``)
411	Dependent on the value, ``if (a) return 0;`` can be put on a
412	single line.
413
414	Possible values:
415
416	* ``SIS_Never`` (in configuration: ``Never``)
417	Do not allow short if functions.
418
419	.. code-block:: c++
420
421	if (a)
422	return;
423	else
424	return;
425
426	* ``SIS_WithoutElse`` (in configuration: ``WithoutElse``)
427	Allow short if functions on the same line, as long as else
428	is not a compound statement.
429
430	.. code-block:: c++
431
432	if (a) return;
433	else
434	return;
435
436	if (a)
437	return;
438	else {
439	return;
440	}
441
442	* ``SIS_Always`` (in configuration: ``Always``)
443	Allow short if statements even if the else is a compound statement.
444
445	.. code-block:: c++
446
447	if (a) return;
448	else {
449	return;
450	}
451
452	AllowShortLambdasOnASingleLine (``ShortLambdaStyle``)
453	Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
454	single line.
455
456	Possible values:
457
458	* ``SLS_None`` (in configuration: ``None``)
459	Never merge lambdas into a single line.
460
461	* ``SLS_Empty`` (in configuration: ``Empty``)
462	Only merge empty lambdas.
463
464	.. code-block:: c++
465
466	auto lambda = [](int a) {}
467	auto lambda2 = [](int a) {
468	return a;
469	};
470
471	* ``SLS_Inline`` (in configuration: ``Inline``)
472	Merge lambda into a single line if argument of a function.
473
474	.. code-block:: c++
475
476	auto lambda = [](int a) {
477	return a;
478	};
479	sort(a.begin(), a.end(), ()[] { return x < y; })
480
481	* ``SLS_All`` (in configuration: ``All``)
482	Merge all lambdas fitting on a single line.
483
484	.. code-block:: c++
485
486	auto lambda = [](int a) {}
487	auto lambda2 = [](int a) { return a; };
488
489
490
491	AllowShortLoopsOnASingleLine (``bool``)
492	If ``true``, ``while (true) continue;`` can be put on a single
493	line.
494
495	AlwaysBreakAfterDefinitionReturnType (``DefinitionReturnTypeBreakingStyle``)
496	The function definition return type breaking style to use. This
497	option is deprecated and is retained for backwards compatibility.
498
499	Possible values:
500
501	* ``DRTBS_None`` (in configuration: ``None``)
502	Break after return type automatically.
503	``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
504
505	* ``DRTBS_All`` (in configuration: ``All``)
506	Always break after the return type.
507
508	* ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
509	Always break after the return types of top-level functions.
510
511
512
513	AlwaysBreakAfterReturnType (``ReturnTypeBreakingStyle``)
514	The function declaration return type breaking style to use.
515
516	Possible values:
517
518	* ``RTBS_None`` (in configuration: ``None``)
519	Break after return type automatically.
520	``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
521
522	.. code-block:: c++
523
524	class A {
525	int f() { return 0; };
526	};
527	int f();
528	int f() { return 1; }
529
530	* ``RTBS_All`` (in configuration: ``All``)
531	Always break after the return type.
532
533	.. code-block:: c++
534
535	class A {
536	int
537	f() {
538	return 0;
539	};
540	};
541	int
542	f();
543	int
544	f() {
545	return 1;
546	}
547
548	* ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
549	Always break after the return types of top-level functions.
550
551	.. code-block:: c++
552
553	class A {
554	int f() { return 0; };
555	};
556	int
557	f();
558	int
559	f() {
560	return 1;
561	}
562
563	* ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
564	Always break after the return type of function definitions.
565
566	.. code-block:: c++
567
568	class A {
569	int
570	f() {
571	return 0;
572	};
573	};
574	int f();
575	int
576	f() {
577	return 1;
578	}
579
580	* ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
581	Always break after the return type of top-level definitions.
582
583	.. code-block:: c++
584
585	class A {
586	int f() { return 0; };
587	};
588	int f();
589	int
590	f() {
591	return 1;
592	}
593
594
595
596	AlwaysBreakBeforeMultilineStrings (``bool``)
597	If ``true``, always break before multiline string literals.
598
599	This flag is mean to make cases where there are multiple multiline strings
600	in a file look more consistent. Thus, it will only take effect if wrapping
601	the string at that point leads to it being indented
602	``ContinuationIndentWidth`` spaces from the start of the line.
603
604	.. code-block:: c++
605
606	true: false:
607	aaaa = vs. aaaa = "bbbb"
608	"bbbb" "cccc";
609	"cccc";
610
611	AlwaysBreakTemplateDeclarations (``BreakTemplateDeclarationsStyle``)
612	The template declaration breaking style to use.
613
614	Possible values:
615
616	* ``BTDS_No`` (in configuration: ``No``)
617	Do not force break before declaration.
618	``PenaltyBreakTemplateDeclaration`` is taken into account.
619
620	.. code-block:: c++
621
622	template <typename T> T foo() {
623	}
624	template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
625	int bbbbbbbbbbbbbbbbbbbbb) {
626	}
627
628	* ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
629	Force break after template declaration only when the following
630	declaration spans multiple lines.
631
632	.. code-block:: c++
633
634	template <typename T> T foo() {
635	}
636	template <typename T>
637	T foo(int aaaaaaaaaaaaaaaaaaaaa,
638	int bbbbbbbbbbbbbbbbbbbbb) {
639	}
640
641	* ``BTDS_Yes`` (in configuration: ``Yes``)
642	Always break after template declaration.
643
644	.. code-block:: c++
645
646	template <typename T>
647	T foo() {
648	}
649	template <typename T>
650	T foo(int aaaaaaaaaaaaaaaaaaaaa,
651	int bbbbbbbbbbbbbbbbbbbbb) {
652	}
653
654
655
656	BinPackArguments (``bool``)
657	If ``false``, a function call's arguments will either be all on the
658	same line or will have one line each.
659
660	.. code-block:: c++
661
662	true:
663	void f() {
664	f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
665	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
666	}
667
668	false:
669	void f() {
670	f(aaaaaaaaaaaaaaaaaaaa,
671	aaaaaaaaaaaaaaaaaaaa,
672	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
673	}
674
675	BinPackParameters (``bool``)
676	If ``false``, a function declaration's or function definition's
677	parameters will either all be on the same line or will have one line each.
678
679	.. code-block:: c++
680
681	true:
682	void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
683	int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
684
685	false:
686	void f(int aaaaaaaaaaaaaaaaaaaa,
687	int aaaaaaaaaaaaaaaaaaaa,
688	int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
689
690	BraceWrapping (``BraceWrappingFlags``)
691	Control of individual brace wrapping cases.
692
693	If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
694	each individual brace case should be handled. Otherwise, this is ignored.
695
696	.. code-block:: yaml
697
698	# Example of usage:
699	BreakBeforeBraces: Custom
700	BraceWrapping:
701	AfterEnum: true
702	AfterStruct: false
703	SplitEmptyFunction: false
704
705	Nested configuration flags:
706
707
708	* ``bool AfterClass`` Wrap class definitions.
709
710	.. code-block:: c++
711
712	true:
713	class foo {};
714
715	false:
716	class foo
717	{};
718
719	* ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
720
721	.. code-block:: c++
722
723	true:
724	if (foo())
725	{
726	} else
727	{}
728	for (int i = 0; i < 10; ++i)
729	{}
730
731	false:
732	if (foo()) {
733	} else {
734	}
735	for (int i = 0; i < 10; ++i) {
736	}
737
738	* ``bool AfterEnum`` Wrap enum definitions.
739
740	.. code-block:: c++
741
742	true:
743	enum X : int
744	{
745	B
746	};
747
748	false:
749	enum X : int { B };
750
751	* ``bool AfterFunction`` Wrap function definitions.
752
753	.. code-block:: c++
754
755	true:
756	void foo()
757	{
758	bar();
759	bar2();
760	}
761
762	false:
763	void foo() {
764	bar();
765	bar2();
766	}
767
768	* ``bool AfterNamespace`` Wrap namespace definitions.
769
770	.. code-block:: c++
771
772	true:
773	namespace
774	{
775	int foo();
776	int bar();
777	}
778
779	false:
780	namespace {
781	int foo();
782	int bar();
783	}
784
785	* ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
786	@autoreleasepool and @synchronized blocks are wrapped
787	according to `AfterControlStatement` flag.
788
789	* ``bool AfterStruct`` Wrap struct definitions.
790
791	.. code-block:: c++
792
793	true:
794	struct foo
795	{
796	int x;
797	};
798
799	false:
800	struct foo {
801	int x;
802	};
803
804	* ``bool AfterUnion`` Wrap union definitions.
805
806	.. code-block:: c++
807
808	true:
809	union foo
810	{
811	int x;
812	}
813
814	false:
815	union foo {
816	int x;
817	}
818
819	* ``bool AfterExternBlock`` Wrap extern blocks.
820
821	.. code-block:: c++
822
823	true:
824	extern "C"
825	{
826	int foo();
827	}
828
829	false:
830	extern "C" {
831	int foo();
832	}
833
834	* ``bool BeforeCatch`` Wrap before ``catch``.
835
836	.. code-block:: c++
837
838	true:
839	try {
840	foo();
841	}
842	catch () {
843	}
844
845	false:
846	try {
847	foo();
848	} catch () {
849	}
850
851	* ``bool BeforeElse`` Wrap before ``else``.
852
853	.. code-block:: c++
854
855	true:
856	if (foo()) {
857	}
858	else {
859	}
860
861	false:
862	if (foo()) {
863	} else {
864	}
865
866	* ``bool IndentBraces`` Indent the wrapped braces themselves.
867
868	* ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
869	This option is used only if the opening brace of the function has
870	already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
871	set, and the function could/should not be put on a single line (as per
872	`AllowShortFunctionsOnASingleLine` and constructor formatting options).
873
874	.. code-block:: c++
875
876	int f() vs. inf f()
877	{} {
878	}
879
880	* ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
881	can be put on a single line. This option is used only if the opening
882	brace of the record has already been wrapped, i.e. the `AfterClass`
883	(for classes) brace wrapping mode is set.
884
885	.. code-block:: c++
886
887	class Foo vs. class Foo
888	{} {
889	}
890
891	* ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
892	This option is used only if the opening brace of the namespace has
893	already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
894	set.
895
896	.. code-block:: c++
897
898	namespace Foo vs. namespace Foo
899	{} {
900	}
901
902
903	BreakAfterJavaFieldAnnotations (``bool``)
904	Break after each annotation on a field in Java files.
905
906	.. code-block:: java
907
908	true: false:
909	@Partial vs. @Partial @Mock DataLoad loader;
910	@Mock
911	DataLoad loader;
912
913	BreakBeforeBinaryOperators (``BinaryOperatorStyle``)
914	The way to wrap binary operators.
915
916	Possible values:
917
918	* ``BOS_None`` (in configuration: ``None``)
919	Break after operators.
920
921	.. code-block:: c++
922
923	LooooooooooongType loooooooooooooooooooooongVariable =
924	someLooooooooooooooooongFunction();
925
926	bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
927	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
928	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
929	aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
930	ccccccccccccccccccccccccccccccccccccccccc;
931
932	* ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
933	Break before operators that aren't assignments.
934
935	.. code-block:: c++
936
937	LooooooooooongType loooooooooooooooooooooongVariable =
938	someLooooooooooooooooongFunction();
939
940	bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
941	+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
942	== aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
943	&& aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
944	> ccccccccccccccccccccccccccccccccccccccccc;
945
946	* ``BOS_All`` (in configuration: ``All``)
947	Break before operators.
948
949	.. code-block:: c++
950
951	LooooooooooongType loooooooooooooooooooooongVariable
952	= someLooooooooooooooooongFunction();
953
954	bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
955	+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
956	== aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
957	&& aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
958	> ccccccccccccccccccccccccccccccccccccccccc;
959
960
961
962	BreakBeforeBraces (``BraceBreakingStyle``)
963	The brace breaking style to use.
964
965	Possible values:
966
967	* ``BS_Attach`` (in configuration: ``Attach``)
968	Always attach braces to surrounding context.
969
970	.. code-block:: c++
971
972	try {
973	foo();
974	} catch () {
975	}
976	void foo() { bar(); }
977	class foo {};
978	if (foo()) {
979	} else {
980	}
981	enum X : int { A, B };
982
983	* ``BS_Linux`` (in configuration: ``Linux``)
984	Like ``Attach``, but break before braces on function, namespace and
985	class definitions.
986
987	.. code-block:: c++
988
989	try {
990	foo();
991	} catch () {
992	}
993	void foo() { bar(); }
994	class foo
995	{
996	};
997	if (foo()) {
998	} else {
999	}
1000	enum X : int { A, B };
1001
1002	* ``BS_Mozilla`` (in configuration: ``Mozilla``)
1003	Like ``Attach``, but break before braces on enum, function, and record
1004	definitions.
1005
1006	.. code-block:: c++
1007
1008	try {
1009	foo();
1010	} catch () {
1011	}
1012	void foo() { bar(); }
1013	class foo
1014	{
1015	};
1016	if (foo()) {
1017	} else {
1018	}
1019	enum X : int { A, B };
1020
1021	* ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
1022	Like ``Attach``, but break before function definitions, ``catch``, and
1023	``else``.
1024
1025	.. code-block:: c++
1026
1027	try {
1028	foo();
1029	}
1030	catch () {
1031	}
1032	void foo() { bar(); }
1033	class foo {
1034	};
1035	if (foo()) {
1036	}
1037	else {
1038	}
1039	enum X : int { A, B };
1040
1041	* ``BS_Allman`` (in configuration: ``Allman``)
1042	Always break before braces.
1043
1044	.. code-block:: c++
1045
1046	try
1047	{
1048	foo();
1049	}
1050	catch ()
1051	{
1052	}
1053	void foo() { bar(); }
1054	class foo
1055	{
1056	};
1057	if (foo())
1058	{
1059	}
1060	else
1061	{
1062	}
1063	enum X : int
1064	{
1065	A,
1066	B
1067	};
1068
1069	* ``BS_GNU`` (in configuration: ``GNU``)
1070	Always break before braces and add an extra level of indentation to
1071	braces of control statements, not to those of class, function
1072	or other definitions.
1073
1074	.. code-block:: c++
1075
1076	try
1077	{
1078	foo();
1079	}
1080	catch ()
1081	{
1082	}
1083	void foo() { bar(); }
1084	class foo
1085	{
1086	};
1087	if (foo())
1088	{
1089	}
1090	else
1091	{
1092	}
1093	enum X : int
1094	{
1095	A,
1096	B
1097	};
1098
1099	* ``BS_WebKit`` (in configuration: ``WebKit``)
1100	Like ``Attach``, but break before functions.
1101
1102	.. code-block:: c++
1103
1104	try {
1105	foo();
1106	} catch () {
1107	}
1108	void foo() { bar(); }
1109	class foo {
1110	};
1111	if (foo()) {
1112	} else {
1113	}
1114	enum X : int { A, B };
1115
1116	* ``BS_Custom`` (in configuration: ``Custom``)
1117	Configure each individual brace in `BraceWrapping`.
1118
1119
1120
1121	BreakBeforeTernaryOperators (``bool``)
1122	If ``true``, ternary operators will be placed after line breaks.
1123
1124	.. code-block:: c++
1125
1126	true:
1127	veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
1128	? firstValue
1129	: SecondValueVeryVeryVeryVeryLong;
1130
1131	false:
1132	veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
1133	firstValue :
1134	SecondValueVeryVeryVeryVeryLong;
1135
1136	BreakConstructorInitializers (``BreakConstructorInitializersStyle``)
1137	The constructor initializers style to use.
1138
1139	Possible values:
1140
1141	* ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
1142	Break constructor initializers before the colon and after the commas.
1143
1144	.. code-block:: c++
1145
1146	Constructor()
1147	: initializer1(),
1148	initializer2()
1149
1150	* ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
1151	Break constructor initializers before the colon and commas, and align
1152	the commas with the colon.
1153
1154	.. code-block:: c++
1155
1156	Constructor()
1157	: initializer1()
1158	, initializer2()
1159
1160	* ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
1161	Break constructor initializers after the colon and commas.
1162
1163	.. code-block:: c++
1164
1165	Constructor() :
1166	initializer1(),
1167	initializer2()
1168
1169
1170
1171	BreakInheritanceList (``BreakInheritanceListStyle``)
1172	The inheritance list style to use.
1173
1174	Possible values:
1175
1176	* ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
1177	Break inheritance list before the colon and after the commas.
1178
1179	.. code-block:: c++
1180
1181	class Foo
1182	: Base1,
1183	Base2
1184	{};
1185
1186	* ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
1187	Break inheritance list before the colon and commas, and align
1188	the commas with the colon.
1189
1190	.. code-block:: c++
1191
1192	class Foo
1193	: Base1
1194	, Base2
1195	{};
1196
1197	* ``BILS_AfterColon`` (in configuration: ``AfterColon``)
1198	Break inheritance list after the colon and commas.
1199
1200	.. code-block:: c++
1201
1202	class Foo :
1203	Base1,
1204	Base2
1205	{};
1206
1207
1208
1209	BreakStringLiterals (``bool``)
1210	Allow breaking string literals when formatting.
1211
1212	ColumnLimit (``unsigned``)
1213	The column limit.
1214
1215	A column limit of ``0`` means that there is no column limit. In this case,
1216	clang-format will respect the input's line breaking decisions within
1217	statements unless they contradict other rules.
1218
1219	CommentPragmas (``std::string``)
1220	A regular expression that describes comments with special meaning,
1221	which should not be split into lines or otherwise changed.
1222
1223	.. code-block:: c++
1224
1225	// CommentPragmas: '^ FOOBAR pragma:'
1226	// Will leave the following line unaffected
1227	#include <vector> // FOOBAR pragma: keep
1228
1229	CompactNamespaces (``bool``)
1230	If ``true``, consecutive namespace declarations will be on the same
1231	line. If ``false``, each namespace is declared on a new line.
1232
1233	.. code-block:: c++
1234
1235	true:
1236	namespace Foo { namespace Bar {
1237	}}
1238
1239	false:
1240	namespace Foo {
1241	namespace Bar {
1242	}
1243	}
1244
1245	If it does not fit on a single line, the overflowing namespaces get
1246	wrapped:
1247
1248	.. code-block:: c++
1249
1250	namespace Foo { namespace Bar {
1251	namespace Extra {
1252	}}}
1253
1254	ConstructorInitializerAllOnOneLineOrOnePerLine (``bool``)
1255	If the constructor initializers don't fit on a line, put each
1256	initializer on its own line.
1257
1258	.. code-block:: c++
1259
1260	true:
1261	SomeClass::Constructor()
1262	: aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1263	return 0;
1264	}
1265
1266	false:
1267	SomeClass::Constructor()
1268	: aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
1269	aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1270	return 0;
1271	}
1272
1273	ConstructorInitializerIndentWidth (``unsigned``)
1274	The number of characters to use for indentation of constructor
1275	initializer lists as well as inheritance lists.
1276
1277	ContinuationIndentWidth (``unsigned``)
1278	Indent width for line continuations.
1279
1280	.. code-block:: c++
1281
1282	ContinuationIndentWidth: 2
1283
1284	int i = // VeryVeryVeryVeryVeryLongComment
1285	longFunction( // Again a long comment
1286	arg);
1287
1288	Cpp11BracedListStyle (``bool``)
1289	If ``true``, format braced lists as best suited for C++11 braced
1290	lists.
1291
1292	Important differences:
1293	- No spaces inside the braced list.
1294	- No line break before the closing brace.
1295	- Indentation with the continuation indent, not with the block indent.
1296
1297	Fundamentally, C++11 braced lists are formatted exactly like function
1298	calls would be formatted in their place. If the braced list follows a name
1299	(e.g. a type or variable name), clang-format formats as if the ``{}`` were
1300	the parentheses of a function call with that name. If there is no name,
1301	a zero-length name is assumed.
1302
1303	.. code-block:: c++
1304
1305	true: false:
1306	vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 };
1307	vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} };
1308	f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]);
1309	new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 };
1310
1311	DerivePointerAlignment (``bool``)
1312	If ``true``, analyze the formatted file for the most common
1313	alignment of ``&`` and ``*``.
1314	Pointer and reference alignment styles are going to be updated according
1315	to the preferences found in the file.
1316	``PointerAlignment`` is then used only as fallback.
1317
1318	DisableFormat (``bool``)
1319	Disables formatting completely.
1320
1321	ExperimentalAutoDetectBinPacking (``bool``)
1322	If ``true``, clang-format detects whether function calls and
1323	definitions are formatted with one parameter per line.
1324
1325	Each call can be bin-packed, one-per-line or inconclusive. If it is
1326	inconclusive, e.g. completely on one line, but a decision needs to be
1327	made, clang-format analyzes whether there are other bin-packed cases in
1328	the input file and act accordingly.
1329
1330	NOTE: This is an experimental flag, that might go away or be renamed. Do
1331	not use this in config files, etc. Use at your own risk.
1332
1333	FixNamespaceComments (``bool``)
1334	If ``true``, clang-format adds missing namespace end comments and
1335	fixes invalid existing ones.
1336
1337	.. code-block:: c++
1338
1339	true: false:
1340	namespace a { vs. namespace a {
1341	foo(); foo();
1342	} // namespace a; }
1343
1344	ForEachMacros (``std::vector<std::string>``)
1345	A vector of macros that should be interpreted as foreach loops
1346	instead of as function calls.
1347
1348	These are expected to be macros of the form:
1349
1350	.. code-block:: c++
1351
1352	FOREACH(<variable-declaration>, ...)
1353	<loop-body>
1354
1355	In the .clang-format configuration file, this can be configured like:
1356
1357	.. code-block:: yaml
1358
1359	ForEachMacros: ['RANGES_FOR', 'FOREACH']
1360
1361	For example: BOOST_FOREACH.
1362
1363	IncludeBlocks (``IncludeBlocksStyle``)
1364	Dependent on the value, multiple ``#include`` blocks can be sorted
1365	as one and divided based on category.
1366
1367	Possible values:
1368
1369	* ``IBS_Preserve`` (in configuration: ``Preserve``)
1370	Sort each ``#include`` block separately.
1371
1372	.. code-block:: c++
1373
1374	#include "b.h" into #include "b.h"
1375
1376	#include <lib/main.h> #include "a.h"
1377	#include "a.h" #include <lib/main.h>
1378
1379	* ``IBS_Merge`` (in configuration: ``Merge``)
1380	Merge multiple ``#include`` blocks together and sort as one.
1381
1382	.. code-block:: c++
1383
1384	#include "b.h" into #include "a.h"
1385	#include "b.h"
1386	#include <lib/main.h> #include <lib/main.h>
1387	#include "a.h"
1388
1389	* ``IBS_Regroup`` (in configuration: ``Regroup``)
1390	Merge multiple ``#include`` blocks together and sort as one.
1391	Then split into groups based on category priority. See
1392	``IncludeCategories``.
1393
1394	.. code-block:: c++
1395
1396	#include "b.h" into #include "a.h"
1397	#include "b.h"
1398	#include <lib/main.h>
1399	#include "a.h" #include <lib/main.h>
1400
1401
1402
1403	IncludeCategories (``std::vector<IncludeCategory>``)
1404	Regular expressions denoting the different ``#include`` categories
1405	used for ordering ``#includes``.
1406
1407	`POSIX extended
1408	<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
1409	regular expressions are supported.
1410
1411	These regular expressions are matched against the filename of an include
1412	(including the <> or "") in order. The value belonging to the first
1413	matching regular expression is assigned and ``#includes`` are sorted first
1414	according to increasing category number and then alphabetically within
1415	each category.
1416
1417	If none of the regular expressions match, INT_MAX is assigned as
1418	category. The main header for a source file automatically gets category 0.
1419	so that it is generally kept at the beginning of the ``#includes``
1420	(https://llvm.org/docs/CodingStandards.html#include-style). However, you
1421	can also assign negative priorities if you have certain headers that
1422	always need to be first.
1423
1424	To configure this in the .clang-format file, use:
1425
1426	.. code-block:: yaml
1427
1428	IncludeCategories:
1429	- Regex: '^"(llvm\|llvm-c\|clang\|clang-c)/'
1430	Priority: 2
1431	- Regex: '^(<\|"(gtest\|gmock\|isl\|json)/)'
1432	Priority: 3
1433	- Regex: '<[[:alnum:].]+>'
1434	Priority: 4
1435	- Regex: '.*'
1436	Priority: 1
1437
1438	IncludeIsMainRegex (``std::string``)
1439	Specify a regular expression of suffixes that are allowed in the
1440	file-to-main-include mapping.
1441
1442	When guessing whether a #include is the "main" include (to assign
1443	category 0, see above), use this regex of allowed suffixes to the header
1444	stem. A partial match is done, so that:
1445	- "" means "arbitrary suffix"
1446	- "$" means "no suffix"
1447
1448	For example, if configured to "(_test)?$", then a header a.h would be seen
1449	as the "main" include in both a.cc and a_test.cc.
1450
1451	IndentCaseLabels (``bool``)
1452	Indent case labels one level from the switch statement.
1453
1454	When ``false``, use the same indentation level as for the switch statement.
1455	Switch statement body is always indented one level more than case labels.
1456
1457	.. code-block:: c++
1458
1459	false: true:
1460	switch (fool) { vs. switch (fool) {
1461	case 1: case 1:
1462	bar(); bar();
1463	break; break;
1464	default: default:
1465	plop(); plop();
1466	} }
1467
1468	IndentPPDirectives (``PPDirectiveIndentStyle``)
1469	The preprocessor directive indenting style to use.
1470
1471	Possible values:
1472
1473	* ``PPDIS_None`` (in configuration: ``None``)
1474	Does not indent any directives.
1475
1476	.. code-block:: c++
1477
1478	#if FOO
1479	#if BAR
1480	#include <foo>
1481	#endif
1482	#endif
1483
1484	* ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
1485	Indents directives after the hash.
1486
1487	.. code-block:: c++
1488
1489	#if FOO
1490	# if BAR
1491	# include <foo>
1492	# endif
1493	#endif
1494
1495	* ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
1496	Indents directives before the hash.
1497
1498	.. code-block:: c++
1499
1500	#if FOO
1501	#if BAR
1502	#include <foo>
1503	#endif
1504	#endif
1505
1506
1507	IndentWidth (``unsigned``)
1508	The number of columns to use for indentation.
1509
1510	.. code-block:: c++
1511
1512	IndentWidth: 3
1513
1514	void f() {
1515	someFunction();
1516	if (true, false) {
1517	f();
1518	}
1519	}
1520
1521	IndentWrappedFunctionNames (``bool``)
1522	Indent if a function definition or declaration is wrapped after the
1523	type.
1524
1525	.. code-block:: c++
1526
1527	true:
1528	LoooooooooooooooooooooooooooooooooooooooongReturnType
1529	LoooooooooooooooooooooooooooooooongFunctionDeclaration();
1530
1531	false:
1532	LoooooooooooooooooooooooooooooooooooooooongReturnType
1533	LoooooooooooooooooooooooooooooooongFunctionDeclaration();
1534
1535	JavaImportGroups (``std::vector<std::string>``)
1536	A vector of prefixes ordered by the desired groups for Java imports.
1537
1538	Each group is separated by a newline. Static imports will also follow the
1539	same grouping convention above all non-static imports. One group's prefix
1540	can be a subset of another - the longest prefix is always matched. Within
1541	a group, the imports are ordered lexicographically.
1542
1543	In the .clang-format configuration file, this can be configured like
1544	in the following yaml example. This will result in imports being
1545	formatted as in the Java example below.
1546
1547	.. code-block:: yaml
1548
1549	JavaImportGroups: ['com.example', 'com', 'org']
1550
1551
1552	.. code-block:: java
1553
1554	import static com.example.function1;
1555
1556	import static com.test.function2;
1557
1558	import static org.example.function3;
1559
1560	import com.example.ClassA;
1561	import com.example.Test;
1562	import com.example.a.ClassB;
1563
1564	import com.test.ClassC;
1565
1566	import org.example.ClassD;
1567
1568	JavaScriptQuotes (``JavaScriptQuoteStyle``)
1569	The JavaScriptQuoteStyle to use for JavaScript strings.
1570
1571	Possible values:
1572
1573	* ``JSQS_Leave`` (in configuration: ``Leave``)
1574	Leave string quotes as they are.
1575
1576	.. code-block:: js
1577
1578	string1 = "foo";
1579	string2 = 'bar';
1580
1581	* ``JSQS_Single`` (in configuration: ``Single``)
1582	Always use single quotes.
1583
1584	.. code-block:: js
1585
1586	string1 = 'foo';
1587	string2 = 'bar';
1588
1589	* ``JSQS_Double`` (in configuration: ``Double``)
1590	Always use double quotes.
1591
1592	.. code-block:: js
1593
1594	string1 = "foo";
1595	string2 = "bar";
1596
1597
1598
1599	JavaScriptWrapImports (``bool``)
1600	Whether to wrap JavaScript import/export statements.
1601
1602	.. code-block:: js
1603
1604	true:
1605	import {
1606	VeryLongImportsAreAnnoying,
1607	VeryLongImportsAreAnnoying,
1608	VeryLongImportsAreAnnoying,
1609	} from 'some/module.js'
1610
1611	false:
1612	import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
1613
1614	KeepEmptyLinesAtTheStartOfBlocks (``bool``)
1615	If true, the empty line at the start of blocks is kept.
1616
1617	.. code-block:: c++
1618
1619	true: false:
1620	if (foo) { vs. if (foo) {
1621	bar();
1622	bar(); }
1623	}
1624
1625	Language (``LanguageKind``)
1626	Language, this format style is targeted at.
1627
1628	Possible values:
1629
1630	* ``LK_None`` (in configuration: ``None``)
1631	Do not use.
1632
1633	* ``LK_Cpp`` (in configuration: ``Cpp``)
1634	Should be used for C, C++.
1635
1636	* ``LK_CSharp`` (in configuration: ``CSharp``)
1637	Should be used for C#.
1638
1639	* ``LK_Java`` (in configuration: ``Java``)
1640	Should be used for Java.
1641
1642	* ``LK_JavaScript`` (in configuration: ``JavaScript``)
1643	Should be used for JavaScript.
1644
1645	* ``LK_ObjC`` (in configuration: ``ObjC``)
1646	Should be used for Objective-C, Objective-C++.
1647
1648	* ``LK_Proto`` (in configuration: ``Proto``)
1649	Should be used for Protocol Buffers
1650	(https://developers.google.com/protocol-buffers/).
1651
1652	* ``LK_TableGen`` (in configuration: ``TableGen``)
1653	Should be used for TableGen code.
1654
1655	* ``LK_TextProto`` (in configuration: ``TextProto``)
1656	Should be used for Protocol Buffer messages in text format
1657	(https://developers.google.com/protocol-buffers/).
1658
1659
1660
1661	MacroBlockBegin (``std::string``)
1662	A regular expression matching macros that start a block.
1663
1664	.. code-block:: c++
1665
1666	# With:
1667	MacroBlockBegin: "^NS_MAP_BEGIN\|\
1668	NS_TABLE_HEAD$"
1669	MacroBlockEnd: "^\
1670	NS_MAP_END\|\
1671	NS_TABLE_.*_END$"
1672
1673	NS_MAP_BEGIN
1674	foo();
1675	NS_MAP_END
1676
1677	NS_TABLE_HEAD
1678	bar();
1679	NS_TABLE_FOO_END
1680
1681	# Without:
1682	NS_MAP_BEGIN
1683	foo();
1684	NS_MAP_END
1685
1686	NS_TABLE_HEAD
1687	bar();
1688	NS_TABLE_FOO_END
1689
1690	MacroBlockEnd (``std::string``)
1691	A regular expression matching macros that end a block.
1692
1693	MaxEmptyLinesToKeep (``unsigned``)
1694	The maximum number of consecutive empty lines to keep.
1695
1696	.. code-block:: c++
1697
1698	MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
1699	int f() { int f() {
1700	int = 1; int i = 1;
1701	i = foo();
1702	i = foo(); return i;
1703	}
1704	return i;
1705	}
1706
1707	NamespaceIndentation (``NamespaceIndentationKind``)
1708	The indentation used for namespaces.
1709
1710	Possible values:
1711
1712	* ``NI_None`` (in configuration: ``None``)
1713	Don't indent in namespaces.
1714
1715	.. code-block:: c++
1716
1717	namespace out {
1718	int i;
1719	namespace in {
1720	int i;
1721	}
1722	}
1723
1724	* ``NI_Inner`` (in configuration: ``Inner``)
1725	Indent only in inner namespaces (nested in other namespaces).
1726
1727	.. code-block:: c++
1728
1729	namespace out {
1730	int i;
1731	namespace in {
1732	int i;
1733	}
1734	}
1735
1736	* ``NI_All`` (in configuration: ``All``)
1737	Indent in all namespaces.
1738
1739	.. code-block:: c++
1740
1741	namespace out {
1742	int i;
1743	namespace in {
1744	int i;
1745	}
1746	}
1747
1748
1749
1750	ObjCBinPackProtocolList (``BinPackStyle``)
1751	Controls bin-packing Objective-C protocol conformance list
1752	items into as few lines as possible when they go over ``ColumnLimit``.
1753
1754	If ``Auto`` (the default), delegates to the value in
1755	``BinPackParameters``. If that is ``true``, bin-packs Objective-C
1756	protocol conformance list items into as few lines as possible
1757	whenever they go over ``ColumnLimit``.
1758
1759	If ``Always``, always bin-packs Objective-C protocol conformance
1760	list items into as few lines as possible whenever they go over
1761	``ColumnLimit``.
1762
1763	If ``Never``, lays out Objective-C protocol conformance list items
1764	onto individual lines whenever they go over ``ColumnLimit``.
1765
1766
1767	.. code-block:: objc
1768
1769	Always (or Auto, if BinPackParameters=true):
1770	@interface ccccccccccccc () <
1771	ccccccccccccc, ccccccccccccc,
1772	ccccccccccccc, ccccccccccccc> {
1773	}
1774
1775	Never (or Auto, if BinPackParameters=false):
1776	@interface ddddddddddddd () <
1777	ddddddddddddd,
1778	ddddddddddddd,
1779	ddddddddddddd,
1780	ddddddddddddd> {
1781	}
1782
1783	Possible values:
1784
1785	* ``BPS_Auto`` (in configuration: ``Auto``)
1786	Automatically determine parameter bin-packing behavior.
1787
1788	* ``BPS_Always`` (in configuration: ``Always``)
1789	Always bin-pack parameters.
1790
1791	* ``BPS_Never`` (in configuration: ``Never``)
1792	Never bin-pack parameters.
1793
1794
1795
1796	ObjCBlockIndentWidth (``unsigned``)
1797	The number of characters to use for indentation of ObjC blocks.
1798
1799	.. code-block:: objc
1800
1801	ObjCBlockIndentWidth: 4
1802
1803	[operation setCompletionBlock:^{
1804	[self onOperationDone];
1805	}];
1806
1807	ObjCSpaceAfterProperty (``bool``)
1808	Add a space after ``@property`` in Objective-C, i.e. use
1809	``@property (readonly)`` instead of ``@property(readonly)``.
1810
1811	ObjCSpaceBeforeProtocolList (``bool``)
1812	Add a space in front of an Objective-C protocol list, i.e. use
1813	``Foo <Protocol>`` instead of ``Foo<Protocol>``.
1814
1815	PenaltyBreakAssignment (``unsigned``)
1816	The penalty for breaking around an assignment operator.
1817
1818	PenaltyBreakBeforeFirstCallParameter (``unsigned``)
1819	The penalty for breaking a function call after ``call(``.
1820
1821	PenaltyBreakComment (``unsigned``)
1822	The penalty for each line break introduced inside a comment.
1823
1824	PenaltyBreakFirstLessLess (``unsigned``)
1825	The penalty for breaking before the first ``<<``.
1826
1827	PenaltyBreakString (``unsigned``)
1828	The penalty for each line break introduced inside a string literal.
1829
1830	PenaltyBreakTemplateDeclaration (``unsigned``)
1831	The penalty for breaking after template declaration.
1832
1833	PenaltyExcessCharacter (``unsigned``)
1834	The penalty for each character outside of the column limit.
1835
1836	PenaltyReturnTypeOnItsOwnLine (``unsigned``)
1837	Penalty for putting the return type of a function onto its own
1838	line.
1839
1840	PointerAlignment (``PointerAlignmentStyle``)
1841	Pointer and reference alignment style.
1842
1843	Possible values:
1844
1845	* ``PAS_Left`` (in configuration: ``Left``)
1846	Align pointer to the left.
1847
1848	.. code-block:: c++
1849
1850	int* a;
1851
1852	* ``PAS_Right`` (in configuration: ``Right``)
1853	Align pointer to the right.
1854
1855	.. code-block:: c++
1856
1857	int *a;
1858
1859	* ``PAS_Middle`` (in configuration: ``Middle``)
1860	Align pointer in the middle.
1861
1862	.. code-block:: c++
1863
1864	int * a;
1865
1866
1867
1868	RawStringFormats (``std::vector<RawStringFormat>``)
1869	Defines hints for detecting supported languages code blocks in raw
1870	strings.
1871
1872	A raw string with a matching delimiter or a matching enclosing function
1873	name will be reformatted assuming the specified language based on the
1874	style for that language defined in the .clang-format file. If no style has
1875	been defined in the .clang-format file for the specific language, a
1876	predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
1877	found, the formatting is based on llvm style. A matching delimiter takes
1878	precedence over a matching enclosing function name for determining the
1879	language of the raw string contents.
1880
1881	If a canonical delimiter is specified, occurrences of other delimiters for
1882	the same language will be updated to the canonical if possible.
1883
1884	There should be at most one specification per language and each delimiter
1885	and enclosing function should not occur in multiple specifications.
1886
1887	To configure this in the .clang-format file, use:
1888
1889	.. code-block:: yaml
1890
1891	RawStringFormats:
1892	- Language: TextProto
1893	Delimiters:
1894	- 'pb'
1895	- 'proto'
1896	EnclosingFunctions:
1897	- 'PARSE_TEXT_PROTO'
1898	BasedOnStyle: google
1899	- Language: Cpp
1900	Delimiters:
1901	- 'cc'
1902	- 'cpp'
1903	BasedOnStyle: llvm
1904	CanonicalDelimiter: 'cc'
1905
1906	ReflowComments (``bool``)
1907	If ``true``, clang-format will attempt to re-flow comments.
1908
1909	.. code-block:: c++
1910
1911	false:
1912	// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
1913	/* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
1914
1915	true:
1916	// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
1917	// information
1918	/* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
1919	* information */
1920
1921	SortIncludes (``bool``)
1922	If ``true``, clang-format will sort ``#includes``.
1923
1924	.. code-block:: c++
1925
1926	false: true:
1927	#include "b.h" vs. #include "a.h"
1928	#include "a.h" #include "b.h"
1929
1930	SortUsingDeclarations (``bool``)
1931	If ``true``, clang-format will sort using declarations.
1932
1933	The order of using declarations is defined as follows:
1934	Split the strings by "::" and discard any initial empty strings. The last
1935	element of each list is a non-namespace name; all others are namespace
1936	names. Sort the lists of names lexicographically, where the sort order of
1937	individual names is that all non-namespace names come before all namespace
1938	names, and within those groups, names are in case-insensitive
1939	lexicographic order.
1940
1941	.. code-block:: c++
1942
1943	false: true:
1944	using std::cout; vs. using std::cin;
1945	using std::cin; using std::cout;
1946
1947	SpaceAfterCStyleCast (``bool``)
1948	If ``true``, a space is inserted after C style casts.
1949
1950	.. code-block:: c++
1951
1952	true: false:
1953	(int) i; vs. (int)i;
1954
1955	SpaceAfterTemplateKeyword (``bool``)
1956	If ``true``, a space will be inserted after the 'template' keyword.
1957
1958	.. code-block:: c++
1959
1960	true: false:
1961	template <int> void foo(); vs. template<int> void foo();
1962
1963	SpaceBeforeAssignmentOperators (``bool``)
1964	If ``false``, spaces will be removed before assignment operators.
1965
1966	.. code-block:: c++
1967
1968	true: false:
1969	int a = 5; vs. int a=5;
1970	a += 42 a+=42;
1971
1972	SpaceBeforeCpp11BracedList (``bool``)
1973	If ``true``, a space will be inserted before a C++11 braced list
1974	used to initialize an object (after the preceding identifier or type).
1975
1976	.. code-block:: c++
1977
1978	true: false:
1979	Foo foo { bar }; vs. Foo foo{ bar };
1980	Foo {}; Foo{};
1981	vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
1982	new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
1983
1984	SpaceBeforeCtorInitializerColon (``bool``)
1985	If ``false``, spaces will be removed before constructor initializer
1986	colon.
1987
1988	.. code-block:: c++
1989
1990	true: false:
1991	Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
1992
1993	SpaceBeforeInheritanceColon (``bool``)
1994	If ``false``, spaces will be removed before inheritance colon.
1995
1996	.. code-block:: c++
1997
1998	true: false:
1999	class Foo : Bar {} vs. class Foo: Bar {}
2000
2001	SpaceBeforeParens (``SpaceBeforeParensOptions``)
2002	Defines in which cases to put a space before opening parentheses.
2003
2004	Possible values:
2005
2006	* ``SBPO_Never`` (in configuration: ``Never``)
2007	Never put a space before opening parentheses.
2008
2009	.. code-block:: c++
2010
2011	void f() {
2012	if(true) {
2013	f();
2014	}
2015	}
2016
2017	* ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
2018	Put a space before opening parentheses only after control statement
2019	keywords (``for/if/while...``).
2020
2021	.. code-block:: c++
2022
2023	void f() {
2024	if (true) {
2025	f();
2026	}
2027	}
2028
2029	* ``SBPO_Always`` (in configuration: ``Always``)
2030	Always put a space before opening parentheses, except when it's
2031	prohibited by the syntax rules (in function-like macro definitions) or
2032	when determined by other style rules (after unary operators, opening
2033	parentheses, etc.)
2034
2035	.. code-block:: c++
2036
2037	void f () {
2038	if (true) {
2039	f ();
2040	}
2041	}
2042
2043
2044
2045	SpaceBeforeRangeBasedForLoopColon (``bool``)
2046	If ``false``, spaces will be removed before range-based for loop
2047	colon.
2048
2049	.. code-block:: c++
2050
2051	true: false:
2052	for (auto v : values) {} vs. for(auto v: values) {}
2053
2054	SpaceInEmptyParentheses (``bool``)
2055	If ``true``, spaces may be inserted into ``()``.
2056
2057	.. code-block:: c++
2058
2059	true: false:
2060	void f( ) { vs. void f() {
2061	int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
2062	if (true) { if (true) {
2063	f( ); f();
2064	} }
2065	} }
2066
2067	SpacesBeforeTrailingComments (``unsigned``)
2068	The number of spaces before trailing line comments
2069	(``//`` - comments).
2070
2071	This does not affect trailing block comments (``/*`` - comments) as
2072	those commonly have different usage patterns and a number of special
2073	cases.
2074
2075	.. code-block:: c++
2076
2077	SpacesBeforeTrailingComments: 3
2078	void f() {
2079	if (true) { // foo1
2080	f(); // bar
2081	} // foo
2082	}
2083
2084	SpacesInAngles (``bool``)
2085	If ``true``, spaces will be inserted after ``<`` and before ``>``
2086	in template argument lists.
2087
2088	.. code-block:: c++
2089
2090	true: false:
2091	static_cast< int >(arg); vs. static_cast<int>(arg);
2092	std::function< void(int) > fct; std::function<void(int)> fct;
2093
2094	SpacesInCStyleCastParentheses (``bool``)
2095	If ``true``, spaces may be inserted into C style casts.
2096
2097	.. code-block:: c++
2098
2099	true: false:
2100	x = ( int32 )y vs. x = (int32)y
2101
2102	SpacesInContainerLiterals (``bool``)
2103	If ``true``, spaces are inserted inside container literals (e.g.
2104	ObjC and Javascript array and dict literals).
2105
2106	.. code-block:: js
2107
2108	true: false:
2109	var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
2110	f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
2111
2112	SpacesInParentheses (``bool``)
2113	If ``true``, spaces will be inserted after ``(`` and before ``)``.
2114
2115	.. code-block:: c++
2116
2117	true: false:
2118	t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
2119
2120	SpacesInSquareBrackets (``bool``)
2121	If ``true``, spaces will be inserted after ``[`` and before ``]``.
2122	Lambdas or unspecified size array declarations will not be affected.
2123
2124	.. code-block:: c++
2125
2126	true: false:
2127	int a[ 5 ]; vs. int a[5];
2128	std::unique_ptr<int[]> foo() {} // Won't be affected
2129
2130	Standard (``LanguageStandard``)
2131	Format compatible with this standard, e.g. use ``A<A<int> >``
2132	instead of ``A<A<int>>`` for ``LS_Cpp03``.
2133
2134	Possible values:
2135
2136	* ``LS_Cpp03`` (in configuration: ``Cpp03``)
2137	Use C++03-compatible syntax.
2138
2139	* ``LS_Cpp11`` (in configuration: ``Cpp11``)
2140	Use features of C++11, C++14 and C++1z (e.g. ``A<A<int>>`` instead of
2141	``A<A<int> >``).
2142
2143	* ``LS_Auto`` (in configuration: ``Auto``)
2144	Automatic detection based on the input.
2145
2146
2147
2148	StatementMacros (``std::vector<std::string>``)
2149	A vector of macros that should be interpreted as complete
2150	statements.
2151
2152	Typical macros are expressions, and require a semi-colon to be
2153	added; sometimes this is not the case, and this allows to make
2154	clang-format aware of such cases.
2155
2156	For example: Q_UNUSED
2157
2158	TabWidth (``unsigned``)
2159	The number of columns used for tab stops.
2160
2161	UseTab (``UseTabStyle``)
2162	The way to use tab characters in the resulting file.
2163
2164	Possible values:
2165
2166	* ``UT_Never`` (in configuration: ``Never``)
2167	Never use tab.
2168
2169	* ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
2170	Use tabs only for indentation.
2171
2172	* ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
2173	Use tabs only for line continuation and indentation.
2174
2175	* ``UT_Always`` (in configuration: ``Always``)
2176	Use tabs whenever we need to fill whitespace that spans at least from
2177	one tab stop to the next one.
2178
2179
2180
2181	.. END_FORMAT_STYLE_OPTIONS
2182
2183	Adding additional style options
2184	===============================
2185
2186	Each additional style option adds costs to the clang-format project. Some of
2187	these costs affect the clang-format development itself, as we need to make
2188	sure that any given combination of options work and that new features don't
2189	break any of the existing options in any way. There are also costs for end users
2190	as options become less discoverable and people have to think about and make a
2191	decision on options they don't really care about.
2192
2193	The goal of the clang-format project is more on the side of supporting a
2194	limited set of styles really well as opposed to supporting every single style
2195	used by a codebase somewhere in the wild. Of course, we do want to support all
2196	major projects and thus have established the following bar for adding style
2197	options. Each new style option must ..
2198
2199	* be used in a project of significant size (have dozens of contributors)
2200	* have a publicly accessible style guide
2201	* have a person willing to contribute and maintain patches
2202
2203	Examples
2204	========
2205
2206	A style similar to the `Linux Kernel style
2207	<https://www.kernel.org/doc/Documentation/CodingStyle>`_:
2208
2209	.. code-block:: yaml
2210
2211	BasedOnStyle: LLVM
2212	IndentWidth: 8
2213	UseTab: Always
2214	BreakBeforeBraces: Linux
2215	AllowShortIfStatementsOnASingleLine: false
2216	IndentCaseLabels: false
2217
2218	The result is (imagine that tabs are used for indentation here):
2219
2220	.. code-block:: c++
2221
2222	void test()
2223	{
2224	switch (x) {
2225	case 0:
2226	case 1:
2227	do_something();
2228	break;
2229	case 2:
2230	do_something_else();
2231	break;
2232	default:
2233	break;
2234	}
2235	if (condition)
2236	do_something_completely_different();
2237
2238	if (x == y) {
2239	q();
2240	} else if (x > y) {
2241	w();
2242	} else {
2243	r();
2244	}
2245	}
2246
2247	A style similar to the default Visual Studio formatting style:
2248
2249	.. code-block:: yaml
2250
2251	UseTab: Never
2252	IndentWidth: 4
2253	BreakBeforeBraces: Allman
2254	AllowShortIfStatementsOnASingleLine: false
2255	IndentCaseLabels: false
2256	ColumnLimit: 0
2257
2258	The result is:
2259
2260	.. code-block:: c++
2261
2262	void test()
2263	{
2264	switch (suffix)
2265	{
2266	case 0:
2267	case 1:
2268	do_something();
2269	break;
2270	case 2:
2271	do_something_else();
2272	break;
2273	default:
2274	break;
2275	}
2276	if (condition)
2277	do_somthing_completely_different();
2278
2279	if (x == y)
2280	{
2281	q();
2282	}
2283	else if (x > y)
2284	{
2285	w();
2286	}
2287	else
2288	{
2289	r();
2290	}
2291	}
2292

Clang Project