1 //===--- Format.h - Format C++ code -----------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// Various functions to configurably format source code.
11 ///
12 //===----------------------------------------------------------------------===//
13
14 #ifndef LLVM_CLANG_FORMAT_FORMAT_H
15 #define LLVM_CLANG_FORMAT_FORMAT_H
16
17 #include "clang/Basic/LangOptions.h"
18 #include "clang/Tooling/Core/Replacement.h"
19 #include "clang/Tooling/Inclusions/IncludeStyle.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/Support/Regex.h"
22 #include "llvm/Support/SourceMgr.h"
23 #include <system_error>
24
25 namespace llvm {
26 namespace vfs {
27 class FileSystem;
28 }
29 } // namespace llvm
30
31 namespace clang {
32
33 class Lexer;
34 class SourceManager;
35 class DiagnosticConsumer;
36
37 namespace format {
38
39 enum class ParseError {
40 Success = 0,
41 Error,
42 Unsuitable,
43 BinPackTrailingCommaConflict
44 };
45 class ParseErrorCategory final : public std::error_category {
46 public:
47 const char *name() const noexcept override;
48 std::string message(int EV) const override;
49 };
50 const std::error_category &getParseCategory();
51 std::error_code make_error_code(ParseError e);
52
53 /// The ``FormatStyle`` is used to configure the formatting to follow
54 /// specific guidelines.
55 struct FormatStyle {
56 // If the BasedOn: was InheritParentConfig and this style needs the file from
57 // the parent directories. It is not part of the actual style for formatting.
58 // Thus the // instead of ///.
59 bool InheritsParentConfig;
60
61 /// The extra indent or outdent of access modifiers, e.g. ``public:``.
62 int AccessModifierOffset;
63
64 /// Different styles for aligning after open brackets.
65 enum BracketAlignmentStyle : unsigned char {
66 /// Align parameters on the open bracket, e.g.:
67 /// \code
68 /// someLongFunction(argument1,
69 /// argument2);
70 /// \endcode
71 BAS_Align,
72 /// Don't align, instead use ``ContinuationIndentWidth``, e.g.:
73 /// \code
74 /// someLongFunction(argument1,
75 /// argument2);
76 /// \endcode
77 BAS_DontAlign,
78 /// Always break after an open bracket, if the parameters don't fit
79 /// on a single line, e.g.:
80 /// \code
81 /// someLongFunction(
82 /// argument1, argument2);
83 /// \endcode
84 BAS_AlwaysBreak,
85 };
86
87 /// If ``true``, horizontally aligns arguments after an open bracket.
88 ///
89 /// This applies to round brackets (parentheses), angle brackets and square
90 /// brackets.
91 BracketAlignmentStyle AlignAfterOpenBracket;
92
93 /// Different style for aligning array initializers.
94 enum ArrayInitializerAlignmentStyle {
95 /// Align array column and left justify the columns e.g.:
96 /// \code
97 /// struct test demo[] =
98 /// {
99 /// {56, 23, "hello"},
100 /// {-1, 93463, "world"},
101 /// {7, 5, "!!" }
102 /// };
103 /// \endcode
104 AIAS_Left,
105 /// Align array column and right justify the columns e.g.:
106 /// \code
107 /// struct test demo[] =
108 /// {
109 /// {56, 23, "hello"},
110 /// {-1, 93463, "world"},
111 /// { 7, 5, "!!"}
112 /// };
113 /// \endcode
114 AIAS_Right,
115 /// Don't align array initializer columns.
116 AIAS_None
117 };
118 /// if not ``None``, when using initialization for an array of structs
119 /// aligns the fields into columns.
120 ArrayInitializerAlignmentStyle AlignArrayOfStructures;
121
122 /// Styles for alignment of consecutive tokens. Tokens can be assignment signs
123 /// (see
124 /// ``AlignConsecutiveAssignments``), bitfield member separators (see
125 /// ``AlignConsecutiveBitFields``), names in declarations (see
126 /// ``AlignConsecutiveDeclarations``) or macro definitions (see
127 /// ``AlignConsecutiveMacros``).
128 enum AlignConsecutiveStyle {
129 ACS_None,
130 ACS_Consecutive,
131 ACS_AcrossEmptyLines,
132 ACS_AcrossComments,
133 ACS_AcrossEmptyLinesAndComments
134 };
135
136 /// Style of aligning consecutive macro definitions.
137 ///
138 /// ``Consecutive`` will result in formattings like:
139 /// \code
140 /// #define SHORT_NAME 42
141 /// #define LONGER_NAME 0x007f
142 /// #define EVEN_LONGER_NAME (2)
143 /// #define foo(x) (x * x)
144 /// #define bar(y, z) (y + z)
145 /// \endcode
146 ///
147 /// Possible values:
148 ///
149 /// * ``ACS_None`` (in configuration: ``None``)
150 /// Do not align macro definitions on consecutive lines.
151 ///
152 /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
153 /// Align macro definitions on consecutive lines. This will result in
154 /// formattings like:
155 /// \code
156 /// #define SHORT_NAME 42
157 /// #define LONGER_NAME 0x007f
158 /// #define EVEN_LONGER_NAME (2)
159 ///
160 /// #define foo(x) (x * x)
161 /// /* some comment */
162 /// #define bar(y, z) (y + z)
163 /// \endcode
164 ///
165 /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
166 /// Same as ACS_Consecutive, but also spans over empty lines, e.g.
167 /// \code
168 /// #define SHORT_NAME 42
169 /// #define LONGER_NAME 0x007f
170 /// #define EVEN_LONGER_NAME (2)
171 ///
172 /// #define foo(x) (x * x)
173 /// /* some comment */
174 /// #define bar(y, z) (y + z)
175 /// \endcode
176 ///
177 /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
178 /// Same as ACS_Consecutive, but also spans over lines only containing
179 /// comments, e.g.
180 /// \code
181 /// #define SHORT_NAME 42
182 /// #define LONGER_NAME 0x007f
183 /// #define EVEN_LONGER_NAME (2)
184 ///
185 /// #define foo(x) (x * x)
186 /// /* some comment */
187 /// #define bar(y, z) (y + z)
188 /// \endcode
189 ///
190 /// * ``ACS_AcrossEmptyLinesAndComments``
191 /// (in configuration: ``AcrossEmptyLinesAndComments``)
192 ///
193 /// Same as ACS_Consecutive, but also spans over lines only containing
194 /// comments and empty lines, e.g.
195 /// \code
196 /// #define SHORT_NAME 42
197 /// #define LONGER_NAME 0x007f
198 /// #define EVEN_LONGER_NAME (2)
199 ///
200 /// #define foo(x) (x * x)
201 /// /* some comment */
202 /// #define bar(y, z) (y + z)
203 /// \endcode
204 AlignConsecutiveStyle AlignConsecutiveMacros;
205
206 /// Style of aligning consecutive assignments.
207 ///
208 /// ``Consecutive`` will result in formattings like:
209 /// \code
210 /// int a = 1;
211 /// int somelongname = 2;
212 /// double c = 3;
213 /// \endcode
214 ///
215 /// Possible values:
216 ///
217 /// * ``ACS_None`` (in configuration: ``None``)
218 /// Do not align assignments on consecutive lines.
219 ///
220 /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
221 /// Align assignments on consecutive lines. This will result in
222 /// formattings like:
223 /// \code
224 /// int a = 1;
225 /// int somelongname = 2;
226 /// double c = 3;
227 ///
228 /// int d = 3;
229 /// /* A comment. */
230 /// double e = 4;
231 /// \endcode
232 ///
233 /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
234 /// Same as ACS_Consecutive, but also spans over empty lines, e.g.
235 /// \code
236 /// int a = 1;
237 /// int somelongname = 2;
238 /// double c = 3;
239 ///
240 /// int d = 3;
241 /// /* A comment. */
242 /// double e = 4;
243 /// \endcode
244 ///
245 /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
246 /// Same as ACS_Consecutive, but also spans over lines only containing
247 /// comments, e.g.
248 /// \code
249 /// int a = 1;
250 /// int somelongname = 2;
251 /// double c = 3;
252 ///
253 /// int d = 3;
254 /// /* A comment. */
255 /// double e = 4;
256 /// \endcode
257 ///
258 /// * ``ACS_AcrossEmptyLinesAndComments``
259 /// (in configuration: ``AcrossEmptyLinesAndComments``)
260 ///
261 /// Same as ACS_Consecutive, but also spans over lines only containing
262 /// comments and empty lines, e.g.
263 /// \code
264 /// int a = 1;
265 /// int somelongname = 2;
266 /// double c = 3;
267 ///
268 /// int d = 3;
269 /// /* A comment. */
270 /// double e = 4;
271 /// \endcode
272 AlignConsecutiveStyle AlignConsecutiveAssignments;
273
274 /// Style of aligning consecutive bit field.
275 ///
276 /// ``Consecutive`` will align the bitfield separators of consecutive lines.
277 /// This will result in formattings like:
278 /// \code
279 /// int aaaa : 1;
280 /// int b : 12;
281 /// int ccc : 8;
282 /// \endcode
283 ///
284 /// Possible values:
285 ///
286 /// * ``ACS_None`` (in configuration: ``None``)
287 /// Do not align bit fields on consecutive lines.
288 ///
289 /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
290 /// Align bit fields on consecutive lines. This will result in
291 /// formattings like:
292 /// \code
293 /// int aaaa : 1;
294 /// int b : 12;
295 /// int ccc : 8;
296 ///
297 /// int d : 2;
298 /// /* A comment. */
299 /// int ee : 3;
300 /// \endcode
301 ///
302 /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
303 /// Same as ACS_Consecutive, but also spans over empty lines, e.g.
304 /// \code
305 /// int aaaa : 1;
306 /// int b : 12;
307 /// int ccc : 8;
308 ///
309 /// int d : 2;
310 /// /* A comment. */
311 /// int ee : 3;
312 /// \endcode
313 ///
314 /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
315 /// Same as ACS_Consecutive, but also spans over lines only containing
316 /// comments, e.g.
317 /// \code
318 /// int aaaa : 1;
319 /// int b : 12;
320 /// int ccc : 8;
321 ///
322 /// int d : 2;
323 /// /* A comment. */
324 /// int ee : 3;
325 /// \endcode
326 ///
327 /// * ``ACS_AcrossEmptyLinesAndComments``
328 /// (in configuration: ``AcrossEmptyLinesAndComments``)
329 ///
330 /// Same as ACS_Consecutive, but also spans over lines only containing
331 /// comments and empty lines, e.g.
332 /// \code
333 /// int aaaa : 1;
334 /// int b : 12;
335 /// int ccc : 8;
336 ///
337 /// int d : 2;
338 /// /* A comment. */
339 /// int ee : 3;
340 /// \endcode
341 AlignConsecutiveStyle AlignConsecutiveBitFields;
342
343 /// Style of aligning consecutive declarations.
344 ///
345 /// ``Consecutive`` will align the declaration names of consecutive lines.
346 /// This will result in formattings like:
347 /// \code
348 /// int aaaa = 12;
349 /// float b = 23;
350 /// std::string ccc;
351 /// \endcode
352 ///
353 /// Possible values:
354 ///
355 /// * ``ACS_None`` (in configuration: ``None``)
356 /// Do not align bit declarations on consecutive lines.
357 ///
358 /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``)
359 /// Align declarations on consecutive lines. This will result in
360 /// formattings like:
361 /// \code
362 /// int aaaa = 12;
363 /// float b = 23;
364 /// std::string ccc;
365 ///
366 /// int a = 42;
367 /// /* A comment. */
368 /// bool c = false;
369 /// \endcode
370 ///
371 /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``)
372 /// Same as ACS_Consecutive, but also spans over empty lines, e.g.
373 /// \code
374 /// int aaaa = 12;
375 /// float b = 23;
376 /// std::string ccc;
377 ///
378 /// int a = 42;
379 /// /* A comment. */
380 /// bool c = false;
381 /// \endcode
382 ///
383 /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``)
384 /// Same as ACS_Consecutive, but also spans over lines only containing
385 /// comments, e.g.
386 /// \code
387 /// int aaaa = 12;
388 /// float b = 23;
389 /// std::string ccc;
390 ///
391 /// int a = 42;
392 /// /* A comment. */
393 /// bool c = false;
394 /// \endcode
395 ///
396 /// * ``ACS_AcrossEmptyLinesAndComments``
397 /// (in configuration: ``AcrossEmptyLinesAndComments``)
398 ///
399 /// Same as ACS_Consecutive, but also spans over lines only containing
400 /// comments and empty lines, e.g.
401 /// \code
402 /// int aaaa = 12;
403 /// float b = 23;
404 /// std::string ccc;
405 ///
406 /// int a = 42;
407 /// /* A comment. */
408 /// bool c = false;
409 /// \endcode
410 AlignConsecutiveStyle AlignConsecutiveDeclarations;
411
412 /// Different styles for aligning escaped newlines.
413 enum EscapedNewlineAlignmentStyle : unsigned char {
414 /// Don't align escaped newlines.
415 /// \code
416 /// #define A \
417 /// int aaaa; \
418 /// int b; \
419 /// int dddddddddd;
420 /// \endcode
421 ENAS_DontAlign,
422 /// Align escaped newlines as far left as possible.
423 /// \code
424 /// true:
425 /// #define A \
426 /// int aaaa; \
427 /// int b; \
428 /// int dddddddddd;
429 ///
430 /// false:
431 /// \endcode
432 ENAS_Left,
433 /// Align escaped newlines in the right-most column.
434 /// \code
435 /// #define A \
436 /// int aaaa; \
437 /// int b; \
438 /// int dddddddddd;
439 /// \endcode
440 ENAS_Right,
441 };
442
443 /// Options for aligning backslashes in escaped newlines.
444 EscapedNewlineAlignmentStyle AlignEscapedNewlines;
445
446 /// Different styles for aligning operands.
447 enum OperandAlignmentStyle : unsigned char {
448 /// Do not align operands of binary and ternary expressions.
449 /// The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
450 /// the start of the line.
451 OAS_DontAlign,
452 /// Horizontally align operands of binary and ternary expressions.
453 ///
454 /// Specifically, this aligns operands of a single expression that needs
455 /// to be split over multiple lines, e.g.:
456 /// \code
457 /// int aaa = bbbbbbbbbbbbbbb +
458 /// ccccccccccccccc;
459 /// \endcode
460 ///
461 /// When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
462 /// aligned with the operand on the first line.
463 /// \code
464 /// int aaa = bbbbbbbbbbbbbbb
465 /// + ccccccccccccccc;
466 /// \endcode
467 OAS_Align,
468 /// Horizontally align operands of binary and ternary expressions.
469 ///
470 /// This is similar to ``AO_Align``, except when
471 /// ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
472 /// that the wrapped operand is aligned with the operand on the first line.
473 /// \code
474 /// int aaa = bbbbbbbbbbbbbbb
475 /// + ccccccccccccccc;
476 /// \endcode
477 OAS_AlignAfterOperator,
478 };
479
480 /// If ``true``, horizontally align operands of binary and ternary
481 /// expressions.
482 OperandAlignmentStyle AlignOperands;
483
484 /// If ``true``, aligns trailing comments.
485 /// \code
486 /// true: false:
487 /// int a; // My comment a vs. int a; // My comment a
488 /// int b = 2; // comment b int b = 2; // comment about b
489 /// \endcode
490 bool AlignTrailingComments;
491
492 /// \brief If a function call or braced initializer list doesn't fit on a
493 /// line, allow putting all arguments onto the next line, even if
494 /// ``BinPackArguments`` is ``false``.
495 /// \code
496 /// true:
497 /// callFunction(
498 /// a, b, c, d);
499 ///
500 /// false:
501 /// callFunction(a,
502 /// b,
503 /// c,
504 /// d);
505 /// \endcode
506 bool AllowAllArgumentsOnNextLine;
507
508 /// \brief If a constructor definition with a member initializer list doesn't
509 /// fit on a single line, allow putting all member initializers onto the next
510 /// line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true.
511 /// Note that this parameter has no effect if
512 /// ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false.
513 /// \code
514 /// true:
515 /// MyClass::MyClass() :
516 /// member0(0), member1(2) {}
517 ///
518 /// false:
519 /// MyClass::MyClass() :
520 /// member0(0),
521 /// member1(2) {}
522 bool AllowAllConstructorInitializersOnNextLine;
523
524 /// If the function declaration doesn't fit on a line,
525 /// allow putting all parameters of a function declaration onto
526 /// the next line even if ``BinPackParameters`` is ``false``.
527 /// \code
528 /// true:
529 /// void myFunction(
530 /// int a, int b, int c, int d, int e);
531 ///
532 /// false:
533 /// void myFunction(int a,
534 /// int b,
535 /// int c,
536 /// int d,
537 /// int e);
538 /// \endcode
539 bool AllowAllParametersOfDeclarationOnNextLine;
540
541 /// Allow short enums on a single line.
542 /// \code
543 /// true:
544 /// enum { A, B } myEnum;
545 ///
546 /// false:
547 /// enum
548 /// {
549 /// A,
550 /// B
551 /// } myEnum;
552 /// \endcode
553 bool AllowShortEnumsOnASingleLine;
554
555 /// Different styles for merging short blocks containing at most one
556 /// statement.
557 enum ShortBlockStyle : unsigned char {
558 /// Never merge blocks into a single line.
559 /// \code
560 /// while (true) {
561 /// }
562 /// while (true) {
563 /// continue;
564 /// }
565 /// \endcode
566 SBS_Never,
567 /// Only merge empty blocks.
568 /// \code
569 /// while (true) {}
570 /// while (true) {
571 /// continue;
572 /// }
573 /// \endcode
574 SBS_Empty,
575 /// Always merge short blocks into a single line.
576 /// \code
577 /// while (true) {}
578 /// while (true) { continue; }
579 /// \endcode
580 SBS_Always,
581 };
582
583 /// Dependent on the value, ``while (true) { continue; }`` can be put on a
584 /// single line.
585 ShortBlockStyle AllowShortBlocksOnASingleLine;
586
587 /// If ``true``, short case labels will be contracted to a single line.
588 /// \code
589 /// true: false:
590 /// switch (a) { vs. switch (a) {
591 /// case 1: x = 1; break; case 1:
592 /// case 2: return; x = 1;
593 /// } break;
594 /// case 2:
595 /// return;
596 /// }
597 /// \endcode
598 bool AllowShortCaseLabelsOnASingleLine;
599
600 /// Different styles for merging short functions containing at most one
601 /// statement.
602 enum ShortFunctionStyle : unsigned char {
603 /// Never merge functions into a single line.
604 SFS_None,
605 /// Only merge functions defined inside a class. Same as "inline",
606 /// except it does not implies "empty": i.e. top level empty functions
607 /// are not merged either.
608 /// \code
609 /// class Foo {
610 /// void f() { foo(); }
611 /// };
612 /// void f() {
613 /// foo();
614 /// }
615 /// void f() {
616 /// }
617 /// \endcode
618 SFS_InlineOnly,
619 /// Only merge empty functions.
620 /// \code
621 /// void f() {}
622 /// void f2() {
623 /// bar2();
624 /// }
625 /// \endcode
626 SFS_Empty,
627 /// Only merge functions defined inside a class. Implies "empty".
628 /// \code
629 /// class Foo {
630 /// void f() { foo(); }
631 /// };
632 /// void f() {
633 /// foo();
634 /// }
635 /// void f() {}
636 /// \endcode
637 SFS_Inline,
638 /// Merge all functions fitting on a single line.
639 /// \code
640 /// class Foo {
641 /// void f() { foo(); }
642 /// };
643 /// void f() { bar(); }
644 /// \endcode
645 SFS_All,
646 };
647
648 /// Dependent on the value, ``int f() { return 0; }`` can be put on a
649 /// single line.
650 ShortFunctionStyle AllowShortFunctionsOnASingleLine;
651
652 /// Different styles for handling short if statements.
653 enum ShortIfStyle : unsigned char {
654 /// Never put short ifs on the same line.
655 /// \code
656 /// if (a)
657 /// return;
658 ///
659 /// if (b)
660 /// return;
661 /// else
662 /// return;
663 ///
664 /// if (c)
665 /// return;
666 /// else {
667 /// return;
668 /// }
669 /// \endcode
670 SIS_Never,
671 /// Put short ifs on the same line only if there is no else statement.
672 /// \code
673 /// if (a) return;
674 ///
675 /// if (b)
676 /// return;
677 /// else
678 /// return;
679 ///
680 /// if (c)
681 /// return;
682 /// else {
683 /// return;
684 /// }
685 /// \endcode
686 SIS_WithoutElse,
687 /// Put short ifs, but not else ifs nor else statements, on the same line.
688 /// \code
689 /// if (a) return;
690 ///
691 /// if (b) return;
692 /// else if (b)
693 /// return;
694 /// else
695 /// return;
696 ///
697 /// if (c) return;
698 /// else {
699 /// return;
700 /// }
701 /// \endcode
702 SIS_OnlyFirstIf,
703 /// Always put short ifs, else ifs and else statements on the same
704 /// line.
705 /// \code
706 /// if (a) return;
707 ///
708 /// if (b) return;
709 /// else return;
710 ///
711 /// if (c) return;
712 /// else {
713 /// return;
714 /// }
715 /// \endcode
716 SIS_AllIfsAndElse,
717 };
718
719 /// Dependent on the value, ``if (a) return;`` can be put on a single line.
720 ShortIfStyle AllowShortIfStatementsOnASingleLine;
721
722 /// Different styles for merging short lambdas containing at most one
723 /// statement.
724 enum ShortLambdaStyle : unsigned char {
725 /// Never merge lambdas into a single line.
726 SLS_None,
727 /// Only merge empty lambdas.
728 /// \code
729 /// auto lambda = [](int a) {}
730 /// auto lambda2 = [](int a) {
731 /// return a;
732 /// };
733 /// \endcode
734 SLS_Empty,
735 /// Merge lambda into a single line if argument of a function.
736 /// \code
737 /// auto lambda = [](int a) {
738 /// return a;
739 /// };
740 /// sort(a.begin(), a.end(), ()[] { return x < y; })
741 /// \endcode
742 SLS_Inline,
743 /// Merge all lambdas fitting on a single line.
744 /// \code
745 /// auto lambda = [](int a) {}
746 /// auto lambda2 = [](int a) { return a; };
747 /// \endcode
748 SLS_All,
749 };
750
751 /// Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
752 /// single line.
753 ShortLambdaStyle AllowShortLambdasOnASingleLine;
754
755 /// If ``true``, ``while (true) continue;`` can be put on a single
756 /// line.
757 bool AllowShortLoopsOnASingleLine;
758
759 /// Different ways to break after the function definition return type.
760 /// This option is **deprecated** and is retained for backwards compatibility.
761 enum DefinitionReturnTypeBreakingStyle : unsigned char {
762 /// Break after return type automatically.
763 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
764 DRTBS_None,
765 /// Always break after the return type.
766 DRTBS_All,
767 /// Always break after the return types of top-level functions.
768 DRTBS_TopLevel,
769 };
770
771 /// Different ways to break after the function definition or
772 /// declaration return type.
773 enum ReturnTypeBreakingStyle : unsigned char {
774 /// Break after return type automatically.
775 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
776 /// \code
777 /// class A {
778 /// int f() { return 0; };
779 /// };
780 /// int f();
781 /// int f() { return 1; }
782 /// \endcode
783 RTBS_None,
784 /// Always break after the return type.
785 /// \code
786 /// class A {
787 /// int
788 /// f() {
789 /// return 0;
790 /// };
791 /// };
792 /// int
793 /// f();
794 /// int
795 /// f() {
796 /// return 1;
797 /// }
798 /// \endcode
799 RTBS_All,
800 /// Always break after the return types of top-level functions.
801 /// \code
802 /// class A {
803 /// int f() { return 0; };
804 /// };
805 /// int
806 /// f();
807 /// int
808 /// f() {
809 /// return 1;
810 /// }
811 /// \endcode
812 RTBS_TopLevel,
813 /// Always break after the return type of function definitions.
814 /// \code
815 /// class A {
816 /// int
817 /// f() {
818 /// return 0;
819 /// };
820 /// };
821 /// int f();
822 /// int
823 /// f() {
824 /// return 1;
825 /// }
826 /// \endcode
827 RTBS_AllDefinitions,
828 /// Always break after the return type of top-level definitions.
829 /// \code
830 /// class A {
831 /// int f() { return 0; };
832 /// };
833 /// int f();
834 /// int
835 /// f() {
836 /// return 1;
837 /// }
838 /// \endcode
839 RTBS_TopLevelDefinitions,
840 };
841
842 /// The function definition return type breaking style to use. This
843 /// option is **deprecated** and is retained for backwards compatibility.
844 DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
845
846 /// The function declaration return type breaking style to use.
847 ReturnTypeBreakingStyle AlwaysBreakAfterReturnType;
848
849 /// If ``true``, always break before multiline string literals.
850 ///
851 /// This flag is mean to make cases where there are multiple multiline strings
852 /// in a file look more consistent. Thus, it will only take effect if wrapping
853 /// the string at that point leads to it being indented
854 /// ``ContinuationIndentWidth`` spaces from the start of the line.
855 /// \code
856 /// true: false:
857 /// aaaa = vs. aaaa = "bbbb"
858 /// "bbbb" "cccc";
859 /// "cccc";
860 /// \endcode
861 bool AlwaysBreakBeforeMultilineStrings;
862
863 /// Different ways to break after the template declaration.
864 enum BreakTemplateDeclarationsStyle : unsigned char {
865 /// Do not force break before declaration.
866 /// ``PenaltyBreakTemplateDeclaration`` is taken into account.
867 /// \code
868 /// template <typename T> T foo() {
869 /// }
870 /// template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
871 /// int bbbbbbbbbbbbbbbbbbbbb) {
872 /// }
873 /// \endcode
874 BTDS_No,
875 /// Force break after template declaration only when the following
876 /// declaration spans multiple lines.
877 /// \code
878 /// template <typename T> T foo() {
879 /// }
880 /// template <typename T>
881 /// T foo(int aaaaaaaaaaaaaaaaaaaaa,
882 /// int bbbbbbbbbbbbbbbbbbbbb) {
883 /// }
884 /// \endcode
885 BTDS_MultiLine,
886 /// Always break after template declaration.
887 /// \code
888 /// template <typename T>
889 /// T foo() {
890 /// }
891 /// template <typename T>
892 /// T foo(int aaaaaaaaaaaaaaaaaaaaa,
893 /// int bbbbbbbbbbbbbbbbbbbbb) {
894 /// }
895 /// \endcode
896 BTDS_Yes
897 };
898
899 /// The template declaration breaking style to use.
900 BreakTemplateDeclarationsStyle AlwaysBreakTemplateDeclarations;
901
902 /// A vector of strings that should be interpreted as attributes/qualifiers
903 /// instead of identifiers. This can be useful for language extensions or
904 /// static analyzer annotations.
905 ///
906 /// For example:
907 /// \code
908 /// x = (char *__capability)&y;
909 /// int function(void) __ununsed;
910 /// void only_writes_to_buffer(char *__output buffer);
911 /// \endcode
912 ///
913 /// In the .clang-format configuration file, this can be configured like:
914 /// \code{.yaml}
915 /// AttributeMacros: ['__capability', '__output', '__ununsed']
916 /// \endcode
917 ///
918 std::vector<std::string> AttributeMacros;
919
920 /// If ``false``, a function call's arguments will either be all on the
921 /// same line or will have one line each.
922 /// \code
923 /// true:
924 /// void f() {
925 /// f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
926 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
927 /// }
928 ///
929 /// false:
930 /// void f() {
931 /// f(aaaaaaaaaaaaaaaaaaaa,
932 /// aaaaaaaaaaaaaaaaaaaa,
933 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
934 /// }
935 /// \endcode
936 bool BinPackArguments;
937
938 /// The style of inserting trailing commas into container literals.
939 enum TrailingCommaStyle : unsigned char {
940 /// Do not insert trailing commas.
941 TCS_None,
942 /// Insert trailing commas in container literals that were wrapped over
943 /// multiple lines. Note that this is conceptually incompatible with
944 /// bin-packing, because the trailing comma is used as an indicator
945 /// that a container should be formatted one-per-line (i.e. not bin-packed).
946 /// So inserting a trailing comma counteracts bin-packing.
947 TCS_Wrapped,
948 };
949
950 /// If set to ``TCS_Wrapped`` will insert trailing commas in container
951 /// literals (arrays and objects) that wrap across multiple lines.
952 /// It is currently only available for JavaScript
953 /// and disabled by default ``TCS_None``.
954 /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
955 /// as inserting the comma disables bin-packing.
956 /// \code
957 /// TSC_Wrapped:
958 /// const someArray = [
959 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
960 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
961 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
962 /// // ^ inserted
963 /// ]
964 /// \endcode
965 TrailingCommaStyle InsertTrailingCommas;
966
967 /// If ``false``, a function declaration's or function definition's
968 /// parameters will either all be on the same line or will have one line each.
969 /// \code
970 /// true:
971 /// void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
972 /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
973 ///
974 /// false:
975 /// void f(int aaaaaaaaaaaaaaaaaaaa,
976 /// int aaaaaaaaaaaaaaaaaaaa,
977 /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
978 /// \endcode
979 bool BinPackParameters;
980
981 /// The style of wrapping parameters on the same line (bin-packed) or
982 /// on one line each.
983 enum BinPackStyle : unsigned char {
984 /// Automatically determine parameter bin-packing behavior.
985 BPS_Auto,
986 /// Always bin-pack parameters.
987 BPS_Always,
988 /// Never bin-pack parameters.
989 BPS_Never,
990 };
991
992 /// The style of breaking before or after binary operators.
993 enum BinaryOperatorStyle : unsigned char {
994 /// Break after operators.
995 /// \code
996 /// LooooooooooongType loooooooooooooooooooooongVariable =
997 /// someLooooooooooooooooongFunction();
998 ///
999 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
1000 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
1001 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
1002 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
1003 /// ccccccccccccccccccccccccccccccccccccccccc;
1004 /// \endcode
1005 BOS_None,
1006 /// Break before operators that aren't assignments.
1007 /// \code
1008 /// LooooooooooongType loooooooooooooooooooooongVariable =
1009 /// someLooooooooooooooooongFunction();
1010 ///
1011 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1012 /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1013 /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1014 /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1015 /// > ccccccccccccccccccccccccccccccccccccccccc;
1016 /// \endcode
1017 BOS_NonAssignment,
1018 /// Break before operators.
1019 /// \code
1020 /// LooooooooooongType loooooooooooooooooooooongVariable
1021 /// = someLooooooooooooooooongFunction();
1022 ///
1023 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1024 /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1025 /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1026 /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1027 /// > ccccccccccccccccccccccccccccccccccccccccc;
1028 /// \endcode
1029 BOS_All,
1030 };
1031
1032 /// The way to wrap binary operators.
1033 BinaryOperatorStyle BreakBeforeBinaryOperators;
1034
1035 /// Different ways to attach braces to their surrounding context.
1036 enum BraceBreakingStyle : unsigned char {
1037 /// Always attach braces to surrounding context.
1038 /// \code
1039 /// namespace N {
1040 /// enum E {
1041 /// E1,
1042 /// E2,
1043 /// };
1044 ///
1045 /// class C {
1046 /// public:
1047 /// C();
1048 /// };
1049 ///
1050 /// bool baz(int i) {
1051 /// try {
1052 /// do {
1053 /// switch (i) {
1054 /// case 1: {
1055 /// foobar();
1056 /// break;
1057 /// }
1058 /// default: {
1059 /// break;
1060 /// }
1061 /// }
1062 /// } while (--i);
1063 /// return true;
1064 /// } catch (...) {
1065 /// handleError();
1066 /// return false;
1067 /// }
1068 /// }
1069 ///
1070 /// void foo(bool b) {
1071 /// if (b) {
1072 /// baz(2);
1073 /// } else {
1074 /// baz(5);
1075 /// }
1076 /// }
1077 ///
1078 /// void bar() { foo(true); }
1079 /// } // namespace N
1080 /// \endcode
1081 BS_Attach,
1082 /// Like ``Attach``, but break before braces on function, namespace and
1083 /// class definitions.
1084 /// \code
1085 /// namespace N
1086 /// {
1087 /// enum E {
1088 /// E1,
1089 /// E2,
1090 /// };
1091 ///
1092 /// class C
1093 /// {
1094 /// public:
1095 /// C();
1096 /// };
1097 ///
1098 /// bool baz(int i)
1099 /// {
1100 /// try {
1101 /// do {
1102 /// switch (i) {
1103 /// case 1: {
1104 /// foobar();
1105 /// break;
1106 /// }
1107 /// default: {
1108 /// break;
1109 /// }
1110 /// }
1111 /// } while (--i);
1112 /// return true;
1113 /// } catch (...) {
1114 /// handleError();
1115 /// return false;
1116 /// }
1117 /// }
1118 ///
1119 /// void foo(bool b)
1120 /// {
1121 /// if (b) {
1122 /// baz(2);
1123 /// } else {
1124 /// baz(5);
1125 /// }
1126 /// }
1127 ///
1128 /// void bar() { foo(true); }
1129 /// } // namespace N
1130 /// \endcode
1131 BS_Linux,
1132 /// Like ``Attach``, but break before braces on enum, function, and record
1133 /// definitions.
1134 /// \code
1135 /// namespace N {
1136 /// enum E
1137 /// {
1138 /// E1,
1139 /// E2,
1140 /// };
1141 ///
1142 /// class C
1143 /// {
1144 /// public:
1145 /// C();
1146 /// };
1147 ///
1148 /// bool baz(int i)
1149 /// {
1150 /// try {
1151 /// do {
1152 /// switch (i) {
1153 /// case 1: {
1154 /// foobar();
1155 /// break;
1156 /// }
1157 /// default: {
1158 /// break;
1159 /// }
1160 /// }
1161 /// } while (--i);
1162 /// return true;
1163 /// } catch (...) {
1164 /// handleError();
1165 /// return false;
1166 /// }
1167 /// }
1168 ///
1169 /// void foo(bool b)
1170 /// {
1171 /// if (b) {
1172 /// baz(2);
1173 /// } else {
1174 /// baz(5);
1175 /// }
1176 /// }
1177 ///
1178 /// void bar() { foo(true); }
1179 /// } // namespace N
1180 /// \endcode
1181 BS_Mozilla,
1182 /// Like ``Attach``, but break before function definitions, ``catch``, and
1183 /// ``else``.
1184 /// \code
1185 /// namespace N {
1186 /// enum E {
1187 /// E1,
1188 /// E2,
1189 /// };
1190 ///
1191 /// class C {
1192 /// public:
1193 /// C();
1194 /// };
1195 ///
1196 /// bool baz(int i)
1197 /// {
1198 /// try {
1199 /// do {
1200 /// switch (i) {
1201 /// case 1: {
1202 /// foobar();
1203 /// break;
1204 /// }
1205 /// default: {
1206 /// break;
1207 /// }
1208 /// }
1209 /// } while (--i);
1210 /// return true;
1211 /// }
1212 /// catch (...) {
1213 /// handleError();
1214 /// return false;
1215 /// }
1216 /// }
1217 ///
1218 /// void foo(bool b)
1219 /// {
1220 /// if (b) {
1221 /// baz(2);
1222 /// }
1223 /// else {
1224 /// baz(5);
1225 /// }
1226 /// }
1227 ///
1228 /// void bar() { foo(true); }
1229 /// } // namespace N
1230 /// \endcode
1231 BS_Stroustrup,
1232 /// Always break before braces.
1233 /// \code
1234 /// namespace N
1235 /// {
1236 /// enum E
1237 /// {
1238 /// E1,
1239 /// E2,
1240 /// };
1241 ///
1242 /// class C
1243 /// {
1244 /// public:
1245 /// C();
1246 /// };
1247 ///
1248 /// bool baz(int i)
1249 /// {
1250 /// try
1251 /// {
1252 /// do
1253 /// {
1254 /// switch (i)
1255 /// {
1256 /// case 1:
1257 /// {
1258 /// foobar();
1259 /// break;
1260 /// }
1261 /// default:
1262 /// {
1263 /// break;
1264 /// }
1265 /// }
1266 /// } while (--i);
1267 /// return true;
1268 /// }
1269 /// catch (...)
1270 /// {
1271 /// handleError();
1272 /// return false;
1273 /// }
1274 /// }
1275 ///
1276 /// void foo(bool b)
1277 /// {
1278 /// if (b)
1279 /// {
1280 /// baz(2);
1281 /// }
1282 /// else
1283 /// {
1284 /// baz(5);
1285 /// }
1286 /// }
1287 ///
1288 /// void bar() { foo(true); }
1289 /// } // namespace N
1290 /// \endcode
1291 BS_Allman,
1292 /// Like ``Allman`` but always indent braces and line up code with braces.
1293 /// \code
1294 /// namespace N
1295 /// {
1296 /// enum E
1297 /// {
1298 /// E1,
1299 /// E2,
1300 /// };
1301 ///
1302 /// class C
1303 /// {
1304 /// public:
1305 /// C();
1306 /// };
1307 ///
1308 /// bool baz(int i)
1309 /// {
1310 /// try
1311 /// {
1312 /// do
1313 /// {
1314 /// switch (i)
1315 /// {
1316 /// case 1:
1317 /// {
1318 /// foobar();
1319 /// break;
1320 /// }
1321 /// default:
1322 /// {
1323 /// break;
1324 /// }
1325 /// }
1326 /// } while (--i);
1327 /// return true;
1328 /// }
1329 /// catch (...)
1330 /// {
1331 /// handleError();
1332 /// return false;
1333 /// }
1334 /// }
1335 ///
1336 /// void foo(bool b)
1337 /// {
1338 /// if (b)
1339 /// {
1340 /// baz(2);
1341 /// }
1342 /// else
1343 /// {
1344 /// baz(5);
1345 /// }
1346 /// }
1347 ///
1348 /// void bar() { foo(true); }
1349 /// } // namespace N
1350 /// \endcode
1351 BS_Whitesmiths,
1352 /// Always break before braces and add an extra level of indentation to
1353 /// braces of control statements, not to those of class, function
1354 /// or other definitions.
1355 /// \code
1356 /// namespace N
1357 /// {
1358 /// enum E
1359 /// {
1360 /// E1,
1361 /// E2,
1362 /// };
1363 ///
1364 /// class C
1365 /// {
1366 /// public:
1367 /// C();
1368 /// };
1369 ///
1370 /// bool baz(int i)
1371 /// {
1372 /// try
1373 /// {
1374 /// do
1375 /// {
1376 /// switch (i)
1377 /// {
1378 /// case 1:
1379 /// {
1380 /// foobar();
1381 /// break;
1382 /// }
1383 /// default:
1384 /// {
1385 /// break;
1386 /// }
1387 /// }
1388 /// }
1389 /// while (--i);
1390 /// return true;
1391 /// }
1392 /// catch (...)
1393 /// {
1394 /// handleError();
1395 /// return false;
1396 /// }
1397 /// }
1398 ///
1399 /// void foo(bool b)
1400 /// {
1401 /// if (b)
1402 /// {
1403 /// baz(2);
1404 /// }
1405 /// else
1406 /// {
1407 /// baz(5);
1408 /// }
1409 /// }
1410 ///
1411 /// void bar() { foo(true); }
1412 /// } // namespace N
1413 /// \endcode
1414 BS_GNU,
1415 /// Like ``Attach``, but break before functions.
1416 /// \code
1417 /// namespace N {
1418 /// enum E {
1419 /// E1,
1420 /// E2,
1421 /// };
1422 ///
1423 /// class C {
1424 /// public:
1425 /// C();
1426 /// };
1427 ///
1428 /// bool baz(int i)
1429 /// {
1430 /// try {
1431 /// do {
1432 /// switch (i) {
1433 /// case 1: {
1434 /// foobar();
1435 /// break;
1436 /// }
1437 /// default: {
1438 /// break;
1439 /// }
1440 /// }
1441 /// } while (--i);
1442 /// return true;
1443 /// } catch (...) {
1444 /// handleError();
1445 /// return false;
1446 /// }
1447 /// }
1448 ///
1449 /// void foo(bool b)
1450 /// {
1451 /// if (b) {
1452 /// baz(2);
1453 /// } else {
1454 /// baz(5);
1455 /// }
1456 /// }
1457 ///
1458 /// void bar() { foo(true); }
1459 /// } // namespace N
1460 /// \endcode
1461 BS_WebKit,
1462 /// Configure each individual brace in `BraceWrapping`.
1463 BS_Custom
1464 };
1465
1466 /// The brace breaking style to use.
1467 BraceBreakingStyle BreakBeforeBraces;
1468
1469 /// Different ways to wrap braces after control statements.
1470 enum BraceWrappingAfterControlStatementStyle : unsigned char {
1471 /// Never wrap braces after a control statement.
1472 /// \code
1473 /// if (foo()) {
1474 /// } else {
1475 /// }
1476 /// for (int i = 0; i < 10; ++i) {
1477 /// }
1478 /// \endcode
1479 BWACS_Never,
1480 /// Only wrap braces after a multi-line control statement.
1481 /// \code
1482 /// if (foo && bar &&
1483 /// baz)
1484 /// {
1485 /// quux();
1486 /// }
1487 /// while (foo || bar) {
1488 /// }
1489 /// \endcode
1490 BWACS_MultiLine,
1491 /// Always wrap braces after a control statement.
1492 /// \code
1493 /// if (foo())
1494 /// {
1495 /// } else
1496 /// {}
1497 /// for (int i = 0; i < 10; ++i)
1498 /// {}
1499 /// \endcode
1500 BWACS_Always
1501 };
1502
1503 /// Precise control over the wrapping of braces.
1504 /// \code
1505 /// # Should be declared this way:
1506 /// BreakBeforeBraces: Custom
1507 /// BraceWrapping:
1508 /// AfterClass: true
1509 /// \endcode
1510 struct BraceWrappingFlags {
1511 /// Wrap case labels.
1512 /// \code
1513 /// false: true:
1514 /// switch (foo) { vs. switch (foo) {
1515 /// case 1: { case 1:
1516 /// bar(); {
1517 /// break; bar();
1518 /// } break;
1519 /// default: { }
1520 /// plop(); default:
1521 /// } {
1522 /// } plop();
1523 /// }
1524 /// }
1525 /// \endcode
1526 bool AfterCaseLabel;
1527 /// Wrap class definitions.
1528 /// \code
1529 /// true:
1530 /// class foo {};
1531 ///
1532 /// false:
1533 /// class foo
1534 /// {};
1535 /// \endcode
1536 bool AfterClass;
1537
1538 /// Wrap control statements (``if``/``for``/``while``/``switch``/..).
1539 BraceWrappingAfterControlStatementStyle AfterControlStatement;
1540 /// Wrap enum definitions.
1541 /// \code
1542 /// true:
1543 /// enum X : int
1544 /// {
1545 /// B
1546 /// };
1547 ///
1548 /// false:
1549 /// enum X : int { B };
1550 /// \endcode
1551 bool AfterEnum;
1552 /// Wrap function definitions.
1553 /// \code
1554 /// true:
1555 /// void foo()
1556 /// {
1557 /// bar();
1558 /// bar2();
1559 /// }
1560 ///
1561 /// false:
1562 /// void foo() {
1563 /// bar();
1564 /// bar2();
1565 /// }
1566 /// \endcode
1567 bool AfterFunction;
1568 /// Wrap namespace definitions.
1569 /// \code
1570 /// true:
1571 /// namespace
1572 /// {
1573 /// int foo();
1574 /// int bar();
1575 /// }
1576 ///
1577 /// false:
1578 /// namespace {
1579 /// int foo();
1580 /// int bar();
1581 /// }
1582 /// \endcode
1583 bool AfterNamespace;
1584 /// Wrap ObjC definitions (interfaces, implementations...).
1585 /// \note @autoreleasepool and @synchronized blocks are wrapped
1586 /// according to `AfterControlStatement` flag.
1587 bool AfterObjCDeclaration;
1588 /// Wrap struct definitions.
1589 /// \code
1590 /// true:
1591 /// struct foo
1592 /// {
1593 /// int x;
1594 /// };
1595 ///
1596 /// false:
1597 /// struct foo {
1598 /// int x;
1599 /// };
1600 /// \endcode
1601 bool AfterStruct;
1602 /// Wrap union definitions.
1603 /// \code
1604 /// true:
1605 /// union foo
1606 /// {
1607 /// int x;
1608 /// }
1609 ///
1610 /// false:
1611 /// union foo {
1612 /// int x;
1613 /// }
1614 /// \endcode
1615 bool AfterUnion;
1616 /// Wrap extern blocks.
1617 /// \code
1618 /// true:
1619 /// extern "C"
1620 /// {
1621 /// int foo();
1622 /// }
1623 ///
1624 /// false:
1625 /// extern "C" {
1626 /// int foo();
1627 /// }
1628 /// \endcode
1629 bool AfterExternBlock; // Partially superseded by IndentExternBlock
1630 /// Wrap before ``catch``.
1631 /// \code
1632 /// true:
1633 /// try {
1634 /// foo();
1635 /// }
1636 /// catch () {
1637 /// }
1638 ///
1639 /// false:
1640 /// try {
1641 /// foo();
1642 /// } catch () {
1643 /// }
1644 /// \endcode
1645 bool BeforeCatch;
1646 /// Wrap before ``else``.
1647 /// \code
1648 /// true:
1649 /// if (foo()) {
1650 /// }
1651 /// else {
1652 /// }
1653 ///
1654 /// false:
1655 /// if (foo()) {
1656 /// } else {
1657 /// }
1658 /// \endcode
1659 bool BeforeElse;
1660 /// Wrap lambda block.
1661 /// \code
1662 /// true:
1663 /// connect(
1664 /// []()
1665 /// {
1666 /// foo();
1667 /// bar();
1668 /// });
1669 ///
1670 /// false:
1671 /// connect([]() {
1672 /// foo();
1673 /// bar();
1674 /// });
1675 /// \endcode
1676 bool BeforeLambdaBody;
1677 /// Wrap before ``while``.
1678 /// \code
1679 /// true:
1680 /// do {
1681 /// foo();
1682 /// }
1683 /// while (1);
1684 ///
1685 /// false:
1686 /// do {
1687 /// foo();
1688 /// } while (1);
1689 /// \endcode
1690 bool BeforeWhile;
1691 /// Indent the wrapped braces themselves.
1692 bool IndentBraces;
1693 /// If ``false``, empty function body can be put on a single line.
1694 /// This option is used only if the opening brace of the function has
1695 /// already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
1696 /// set, and the function could/should not be put on a single line (as per
1697 /// `AllowShortFunctionsOnASingleLine` and constructor formatting options).
1698 /// \code
1699 /// int f() vs. int f()
1700 /// {} {
1701 /// }
1702 /// \endcode
1703 ///
1704 bool SplitEmptyFunction;
1705 /// If ``false``, empty record (e.g. class, struct or union) body
1706 /// can be put on a single line. This option is used only if the opening
1707 /// brace of the record has already been wrapped, i.e. the `AfterClass`
1708 /// (for classes) brace wrapping mode is set.
1709 /// \code
1710 /// class Foo vs. class Foo
1711 /// {} {
1712 /// }
1713 /// \endcode
1714 ///
1715 bool SplitEmptyRecord;
1716 /// If ``false``, empty namespace body can be put on a single line.
1717 /// This option is used only if the opening brace of the namespace has
1718 /// already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
1719 /// set.
1720 /// \code
1721 /// namespace Foo vs. namespace Foo
1722 /// {} {
1723 /// }
1724 /// \endcode
1725 ///
1726 bool SplitEmptyNamespace;
1727 };
1728
1729 /// Control of individual brace wrapping cases.
1730 ///
1731 /// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
1732 /// each individual brace case should be handled. Otherwise, this is ignored.
1733 /// \code{.yaml}
1734 /// # Example of usage:
1735 /// BreakBeforeBraces: Custom
1736 /// BraceWrapping:
1737 /// AfterEnum: true
1738 /// AfterStruct: false
1739 /// SplitEmptyFunction: false
1740 /// \endcode
1741 BraceWrappingFlags BraceWrapping;
1742
1743 /// If ``true``, concept will be placed on a new line.
1744 /// \code
1745 /// true:
1746 /// template<typename T>
1747 /// concept ...
1748 ///
1749 /// false:
1750 /// template<typename T> concept ...
1751 /// \endcode
1752 bool BreakBeforeConceptDeclarations;
1753
1754 /// If ``true``, ternary operators will be placed after line breaks.
1755 /// \code
1756 /// true:
1757 /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
1758 /// ? firstValue
1759 /// : SecondValueVeryVeryVeryVeryLong;
1760 ///
1761 /// false:
1762 /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
1763 /// firstValue :
1764 /// SecondValueVeryVeryVeryVeryLong;
1765 /// \endcode
1766 bool BreakBeforeTernaryOperators;
1767
1768 /// Different ways to break initializers.
1769 enum BreakConstructorInitializersStyle : unsigned char {
1770 /// Break constructor initializers before the colon and after the commas.
1771 /// \code
1772 /// Constructor()
1773 /// : initializer1(),
1774 /// initializer2()
1775 /// \endcode
1776 BCIS_BeforeColon,
1777 /// Break constructor initializers before the colon and commas, and align
1778 /// the commas with the colon.
1779 /// \code
1780 /// Constructor()
1781 /// : initializer1()
1782 /// , initializer2()
1783 /// \endcode
1784 BCIS_BeforeComma,
1785 /// Break constructor initializers after the colon and commas.
1786 /// \code
1787 /// Constructor() :
1788 /// initializer1(),
1789 /// initializer2()
1790 /// \endcode
1791 BCIS_AfterColon
1792 };
1793
1794 /// The constructor initializers style to use.
1795 BreakConstructorInitializersStyle BreakConstructorInitializers;
1796
1797 /// Break after each annotation on a field in Java files.
1798 /// \code{.java}
1799 /// true: false:
1800 /// @Partial vs. @Partial @Mock DataLoad loader;
1801 /// @Mock
1802 /// DataLoad loader;
1803 /// \endcode
1804 bool BreakAfterJavaFieldAnnotations;
1805
1806 /// Allow breaking string literals when formatting.
1807 /// \code
1808 /// true:
1809 /// const char* x = "veryVeryVeryVeryVeryVe"
1810 /// "ryVeryVeryVeryVeryVery"
1811 /// "VeryLongString";
1812 ///
1813 /// false:
1814 /// const char* x =
1815 /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
1816 /// \endcode
1817 bool BreakStringLiterals;
1818
1819 /// The column limit.
1820 ///
1821 /// A column limit of ``0`` means that there is no column limit. In this case,
1822 /// clang-format will respect the input's line breaking decisions within
1823 /// statements unless they contradict other rules.
1824 unsigned ColumnLimit;
1825
1826 /// A regular expression that describes comments with special meaning,
1827 /// which should not be split into lines or otherwise changed.
1828 /// \code
1829 /// // CommentPragmas: '^ FOOBAR pragma:'
1830 /// // Will leave the following line unaffected
1831 /// #include <vector> // FOOBAR pragma: keep
1832 /// \endcode
1833 std::string CommentPragmas;
1834
1835 /// Different ways to break inheritance list.
1836 enum BreakInheritanceListStyle : unsigned char {
1837 /// Break inheritance list before the colon and after the commas.
1838 /// \code
1839 /// class Foo
1840 /// : Base1,
1841 /// Base2
1842 /// {};
1843 /// \endcode
1844 BILS_BeforeColon,
1845 /// Break inheritance list before the colon and commas, and align
1846 /// the commas with the colon.
1847 /// \code
1848 /// class Foo
1849 /// : Base1
1850 /// , Base2
1851 /// {};
1852 /// \endcode
1853 BILS_BeforeComma,
1854 /// Break inheritance list after the colon and commas.
1855 /// \code
1856 /// class Foo :
1857 /// Base1,
1858 /// Base2
1859 /// {};
1860 /// \endcode
1861 BILS_AfterColon,
1862 /// Break inheritance list only after the commas.
1863 /// \code
1864 /// class Foo : Base1,
1865 /// Base2
1866 /// {};
1867 /// \endcode
1868 BILS_AfterComma,
1869 };
1870
1871 /// The inheritance list style to use.
1872 BreakInheritanceListStyle BreakInheritanceList;
1873
1874 /// If ``true``, consecutive namespace declarations will be on the same
1875 /// line. If ``false``, each namespace is declared on a new line.
1876 /// \code
1877 /// true:
1878 /// namespace Foo { namespace Bar {
1879 /// }}
1880 ///
1881 /// false:
1882 /// namespace Foo {
1883 /// namespace Bar {
1884 /// }
1885 /// }
1886 /// \endcode
1887 ///
1888 /// If it does not fit on a single line, the overflowing namespaces get
1889 /// wrapped:
1890 /// \code
1891 /// namespace Foo { namespace Bar {
1892 /// namespace Extra {
1893 /// }}}
1894 /// \endcode
1895 bool CompactNamespaces;
1896
1897 // clang-format off
1898 /// If the constructor initializers don't fit on a line, put each
1899 /// initializer on its own line.
1900 /// \code
1901 /// true:
1902 /// SomeClass::Constructor()
1903 /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1904 /// return 0;
1905 /// }
1906 ///
1907 /// false:
1908 /// SomeClass::Constructor()
1909 /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
1910 /// aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
1911 /// return 0;
1912 /// }
1913 /// \endcode
1914 bool ConstructorInitializerAllOnOneLineOrOnePerLine;
1915 // clang-format on
1916
1917 /// The number of characters to use for indentation of constructor
1918 /// initializer lists as well as inheritance lists.
1919 unsigned ConstructorInitializerIndentWidth;
1920
1921 /// Indent width for line continuations.
1922 /// \code
1923 /// ContinuationIndentWidth: 2
1924 ///
1925 /// int i = // VeryVeryVeryVeryVeryLongComment
1926 /// longFunction( // Again a long comment
1927 /// arg);
1928 /// \endcode
1929 unsigned ContinuationIndentWidth;
1930
1931 /// If ``true``, format braced lists as best suited for C++11 braced
1932 /// lists.
1933 ///
1934 /// Important differences:
1935 /// - No spaces inside the braced list.
1936 /// - No line break before the closing brace.
1937 /// - Indentation with the continuation indent, not with the block indent.
1938 ///
1939 /// Fundamentally, C++11 braced lists are formatted exactly like function
1940 /// calls would be formatted in their place. If the braced list follows a name
1941 /// (e.g. a type or variable name), clang-format formats as if the ``{}`` were
1942 /// the parentheses of a function call with that name. If there is no name,
1943 /// a zero-length name is assumed.
1944 /// \code
1945 /// true: false:
1946 /// vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 };
1947 /// vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} };
1948 /// f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]);
1949 /// new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 };
1950 /// \endcode
1951 bool Cpp11BracedListStyle;
1952
1953 /// \brief Analyze the formatted file for the most used line ending (``\r\n``
1954 /// or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived.
1955 bool DeriveLineEnding;
1956
1957 /// If ``true``, analyze the formatted file for the most common
1958 /// alignment of ``&`` and ``*``.
1959 /// Pointer and reference alignment styles are going to be updated according
1960 /// to the preferences found in the file.
1961 /// ``PointerAlignment`` is then used only as fallback.
1962 bool DerivePointerAlignment;
1963
1964 /// Disables formatting completely.
1965 bool DisableFormat;
1966
1967 /// Different styles for empty line after access modifiers.
1968 /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
1969 /// empty lines between two access modifiers.
1970 enum EmptyLineAfterAccessModifierStyle : unsigned char {
1971 /// Remove all empty lines after access modifiers.
1972 /// \code
1973 /// struct foo {
1974 /// private:
1975 /// int i;
1976 /// protected:
1977 /// int j;
1978 /// /* comment */
1979 /// public:
1980 /// foo() {}
1981 /// private:
1982 /// protected:
1983 /// };
1984 /// \endcode
1985 ELAAMS_Never,
1986 /// Keep existing empty lines after access modifiers.
1987 /// MaxEmptyLinesToKeep is applied instead.
1988 ELAAMS_Leave,
1989 /// Always add empty line after access modifiers if there are none.
1990 /// MaxEmptyLinesToKeep is applied also.
1991 /// \code
1992 /// struct foo {
1993 /// private:
1994 ///
1995 /// int i;
1996 /// protected:
1997 ///
1998 /// int j;
1999 /// /* comment */
2000 /// public:
2001 ///
2002 /// foo() {}
2003 /// private:
2004 ///
2005 /// protected:
2006 ///
2007 /// };
2008 /// \endcode
2009 ELAAMS_Always,
2010 };
2011
2012 /// Defines when to put an empty line after access modifiers.
2013 /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
2014 /// empty lines between two access modifiers.
2015 EmptyLineAfterAccessModifierStyle EmptyLineAfterAccessModifier;
2016
2017 /// Different styles for empty line before access modifiers.
2018 enum EmptyLineBeforeAccessModifierStyle : unsigned char {
2019 /// Remove all empty lines before access modifiers.
2020 /// \code
2021 /// struct foo {
2022 /// private:
2023 /// int i;
2024 /// protected:
2025 /// int j;
2026 /// /* comment */
2027 /// public:
2028 /// foo() {}
2029 /// private:
2030 /// protected:
2031 /// };
2032 /// \endcode
2033 ELBAMS_Never,
2034 /// Keep existing empty lines before access modifiers.
2035 ELBAMS_Leave,
2036 /// Add empty line only when access modifier starts a new logical block.
2037 /// Logical block is a group of one or more member fields or functions.
2038 /// \code
2039 /// struct foo {
2040 /// private:
2041 /// int i;
2042 ///
2043 /// protected:
2044 /// int j;
2045 /// /* comment */
2046 /// public:
2047 /// foo() {}
2048 ///
2049 /// private:
2050 /// protected:
2051 /// };
2052 /// \endcode
2053 ELBAMS_LogicalBlock,
2054 /// Always add empty line before access modifiers unless access modifier
2055 /// is at the start of struct or class definition.
2056 /// \code
2057 /// struct foo {
2058 /// private:
2059 /// int i;
2060 ///
2061 /// protected:
2062 /// int j;
2063 /// /* comment */
2064 ///
2065 /// public:
2066 /// foo() {}
2067 ///
2068 /// private:
2069 ///
2070 /// protected:
2071 /// };
2072 /// \endcode
2073 ELBAMS_Always,
2074 };
2075
2076 /// Defines in which cases to put empty line before access modifiers.
2077 EmptyLineBeforeAccessModifierStyle EmptyLineBeforeAccessModifier;
2078
2079 /// If ``true``, clang-format detects whether function calls and
2080 /// definitions are formatted with one parameter per line.
2081 ///
2082 /// Each call can be bin-packed, one-per-line or inconclusive. If it is
2083 /// inconclusive, e.g. completely on one line, but a decision needs to be
2084 /// made, clang-format analyzes whether there are other bin-packed cases in
2085 /// the input file and act accordingly.
2086 ///
2087 /// NOTE: This is an experimental flag, that might go away or be renamed. Do
2088 /// not use this in config files, etc. Use at your own risk.
2089 bool ExperimentalAutoDetectBinPacking;
2090
2091 /// If ``true``, clang-format adds missing namespace end comments for
2092 /// short namespaces and fixes invalid existing ones. Short ones are
2093 /// controlled by "ShortNamespaceLines".
2094 /// \code
2095 /// true: false:
2096 /// namespace a { vs. namespace a {
2097 /// foo(); foo();
2098 /// bar(); bar();
2099 /// } // namespace a }
2100 /// \endcode
2101 bool FixNamespaceComments;
2102
2103 /// A vector of macros that should be interpreted as foreach loops
2104 /// instead of as function calls.
2105 ///
2106 /// These are expected to be macros of the form:
2107 /// \code
2108 /// FOREACH(<variable-declaration>, ...)
2109 /// <loop-body>
2110 /// \endcode
2111 ///
2112 /// In the .clang-format configuration file, this can be configured like:
2113 /// \code{.yaml}
2114 /// ForEachMacros: ['RANGES_FOR', 'FOREACH']
2115 /// \endcode
2116 ///
2117 /// For example: BOOST_FOREACH.
2118 std::vector<std::string> ForEachMacros;
2119
2120 /// A vector of macros that should be interpreted as conditionals
2121 /// instead of as function calls.
2122 ///
2123 /// These are expected to be macros of the form:
2124 /// \code
2125 /// IF(...)
2126 /// <conditional-body>
2127 /// else IF(...)
2128 /// <conditional-body>
2129 /// \endcode
2130 ///
2131 /// In the .clang-format configuration file, this can be configured like:
2132 /// \code{.yaml}
2133 /// IfMacros: ['IF']
2134 /// \endcode
2135 ///
2136 /// For example: `KJ_IF_MAYBE
2137 /// <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
2138 std::vector<std::string> IfMacros;
2139
2140 /// \brief A vector of macros that should be interpreted as type declarations
2141 /// instead of as function calls.
2142 ///
2143 /// These are expected to be macros of the form:
2144 /// \code
2145 /// STACK_OF(...)
2146 /// \endcode
2147 ///
2148 /// In the .clang-format configuration file, this can be configured like:
2149 /// \code{.yaml}
2150 /// TypenameMacros: ['STACK_OF', 'LIST']
2151 /// \endcode
2152 ///
2153 /// For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
2154 std::vector<std::string> TypenameMacros;
2155
2156 /// A vector of macros that should be interpreted as complete
2157 /// statements.
2158 ///
2159 /// Typical macros are expressions, and require a semi-colon to be
2160 /// added; sometimes this is not the case, and this allows to make
2161 /// clang-format aware of such cases.
2162 ///
2163 /// For example: Q_UNUSED
2164 std::vector<std::string> StatementMacros;
2165
2166 /// A vector of macros which are used to open namespace blocks.
2167 ///
2168 /// These are expected to be macros of the form:
2169 /// \code
2170 /// NAMESPACE(<namespace-name>, ...) {
2171 /// <namespace-content>
2172 /// }
2173 /// \endcode
2174 ///
2175 /// For example: TESTSUITE
2176 std::vector<std::string> NamespaceMacros;
2177
2178 /// A vector of macros which are whitespace-sensitive and should not
2179 /// be touched.
2180 ///
2181 /// These are expected to be macros of the form:
2182 /// \code
2183 /// STRINGIZE(...)
2184 /// \endcode
2185 ///
2186 /// In the .clang-format configuration file, this can be configured like:
2187 /// \code{.yaml}
2188 /// WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE']
2189 /// \endcode
2190 ///
2191 /// For example: BOOST_PP_STRINGIZE
2192 std::vector<std::string> WhitespaceSensitiveMacros;
2193
2194 tooling::IncludeStyle IncludeStyle;
2195
2196 /// Specify whether access modifiers should have their own indentation level.
2197 ///
2198 /// When ``false``, access modifiers are indented (or outdented) relative to
2199 /// the record members, respecting the ``AccessModifierOffset``. Record
2200 /// members are indented one level below the record.
2201 /// When ``true``, access modifiers get their own indentation level. As a
2202 /// consequence, record members are always indented 2 levels below the record,
2203 /// regardless of the access modifier presence. Value of the
2204 /// ``AccessModifierOffset`` is ignored.
2205 /// \code
2206 /// false: true:
2207 /// class C { vs. class C {
2208 /// class D { class D {
2209 /// void bar(); void bar();
2210 /// protected: protected:
2211 /// D(); D();
2212 /// }; };
2213 /// public: public:
2214 /// C(); C();
2215 /// }; };
2216 /// void foo() { void foo() {
2217 /// return 1; return 1;
2218 /// } }
2219 /// \endcode
2220 bool IndentAccessModifiers;
2221
2222 /// Indent case labels one level from the switch statement.
2223 ///
2224 /// When ``false``, use the same indentation level as for the switch
2225 /// statement. Switch statement body is always indented one level more than
2226 /// case labels (except the first block following the case label, which
2227 /// itself indents the code - unless IndentCaseBlocks is enabled).
2228 /// \code
2229 /// false: true:
2230 /// switch (fool) { vs. switch (fool) {
2231 /// case 1: case 1:
2232 /// bar(); bar();
2233 /// break; break;
2234 /// default: default:
2235 /// plop(); plop();
2236 /// } }
2237 /// \endcode
2238 bool IndentCaseLabels;
2239
2240 /// Indent case label blocks one level from the case label.
2241 ///
2242 /// When ``false``, the block following the case label uses the same
2243 /// indentation level as for the case label, treating the case label the same
2244 /// as an if-statement.
2245 /// When ``true``, the block gets indented as a scope block.
2246 /// \code
2247 /// false: true:
2248 /// switch (fool) { vs. switch (fool) {
2249 /// case 1: { case 1:
2250 /// bar(); {
2251 /// } break; bar();
2252 /// default: { }
2253 /// plop(); break;
2254 /// } default:
2255 /// } {
2256 /// plop();
2257 /// }
2258 /// }
2259 /// \endcode
2260 bool IndentCaseBlocks;
2261
2262 /// Indent goto labels.
2263 ///
2264 /// When ``false``, goto labels are flushed left.
2265 /// \code
2266 /// true: false:
2267 /// int f() { vs. int f() {
2268 /// if (foo()) { if (foo()) {
2269 /// label1: label1:
2270 /// bar(); bar();
2271 /// } }
2272 /// label2: label2:
2273 /// return 1; return 1;
2274 /// } }
2275 /// \endcode
2276 bool IndentGotoLabels;
2277
2278 /// Options for indenting preprocessor directives.
2279 enum PPDirectiveIndentStyle : unsigned char {
2280 /// Does not indent any directives.
2281 /// \code
2282 /// #if FOO
2283 /// #if BAR
2284 /// #include <foo>
2285 /// #endif
2286 /// #endif
2287 /// \endcode
2288 PPDIS_None,
2289 /// Indents directives after the hash.
2290 /// \code
2291 /// #if FOO
2292 /// # if BAR
2293 /// # include <foo>
2294 /// # endif
2295 /// #endif
2296 /// \endcode
2297 PPDIS_AfterHash,
2298 /// Indents directives before the hash.
2299 /// \code
2300 /// #if FOO
2301 /// #if BAR
2302 /// #include <foo>
2303 /// #endif
2304 /// #endif
2305 /// \endcode
2306 PPDIS_BeforeHash
2307 };
2308
2309 /// The preprocessor directive indenting style to use.
2310 PPDirectiveIndentStyle IndentPPDirectives;
2311
2312 /// Indents extern blocks
2313 enum IndentExternBlockStyle : unsigned char {
2314 /// Backwards compatible with AfterExternBlock's indenting.
2315 /// \code
2316 /// IndentExternBlock: AfterExternBlock
2317 /// BraceWrapping.AfterExternBlock: true
2318 /// extern "C"
2319 /// {
2320 /// void foo();
2321 /// }
2322 /// \endcode
2323 ///
2324 /// \code
2325 /// IndentExternBlock: AfterExternBlock
2326 /// BraceWrapping.AfterExternBlock: false
2327 /// extern "C" {
2328 /// void foo();
2329 /// }
2330 /// \endcode
2331 IEBS_AfterExternBlock,
2332 /// Does not indent extern blocks.
2333 /// \code
2334 /// extern "C" {
2335 /// void foo();
2336 /// }
2337 /// \endcode
2338 IEBS_NoIndent,
2339 /// Indents extern blocks.
2340 /// \code
2341 /// extern "C" {
2342 /// void foo();
2343 /// }
2344 /// \endcode
2345 IEBS_Indent,
2346 };
2347
2348 /// IndentExternBlockStyle is the type of indenting of extern blocks.
2349 IndentExternBlockStyle IndentExternBlock;
2350
2351 /// Indent the requires clause in a template
2352 /// \code
2353 /// true:
2354 /// template <typename It>
2355 /// requires Iterator<It>
2356 /// void sort(It begin, It end) {
2357 /// //....
2358 /// }
2359 ///
2360 /// false:
2361 /// template <typename It>
2362 /// requires Iterator<It>
2363 /// void sort(It begin, It end) {
2364 /// //....
2365 /// }
2366 /// \endcode
2367 bool IndentRequires;
2368
2369 /// The number of columns to use for indentation.
2370 /// \code
2371 /// IndentWidth: 3
2372 ///
2373 /// void f() {
2374 /// someFunction();
2375 /// if (true, false) {
2376 /// f();
2377 /// }
2378 /// }
2379 /// \endcode
2380 unsigned IndentWidth;
2381
2382 /// Indent if a function definition or declaration is wrapped after the
2383 /// type.
2384 /// \code
2385 /// true:
2386 /// LoooooooooooooooooooooooooooooooooooooooongReturnType
2387 /// LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2388 ///
2389 /// false:
2390 /// LoooooooooooooooooooooooooooooooooooooooongReturnType
2391 /// LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2392 /// \endcode
2393 bool IndentWrappedFunctionNames;
2394
2395 /// A vector of prefixes ordered by the desired groups for Java imports.
2396 ///
2397 /// One group's prefix can be a subset of another - the longest prefix is
2398 /// always matched. Within a group, the imports are ordered lexicographically.
2399 /// Static imports are grouped separately and follow the same group rules.
2400 /// By default, static imports are placed before non-static imports,
2401 /// but this behavior is changed by another option,
2402 /// ``SortJavaStaticImport``.
2403 ///
2404 /// In the .clang-format configuration file, this can be configured like
2405 /// in the following yaml example. This will result in imports being
2406 /// formatted as in the Java example below.
2407 /// \code{.yaml}
2408 /// JavaImportGroups: ['com.example', 'com', 'org']
2409 /// \endcode
2410 ///
2411 /// \code{.java}
2412 /// import static com.example.function1;
2413 ///
2414 /// import static com.test.function2;
2415 ///
2416 /// import static org.example.function3;
2417 ///
2418 /// import com.example.ClassA;
2419 /// import com.example.Test;
2420 /// import com.example.a.ClassB;
2421 ///
2422 /// import com.test.ClassC;
2423 ///
2424 /// import org.example.ClassD;
2425 /// \endcode
2426 std::vector<std::string> JavaImportGroups;
2427
2428 /// Quotation styles for JavaScript strings. Does not affect template
2429 /// strings.
2430 enum JavaScriptQuoteStyle : unsigned char {
2431 /// Leave string quotes as they are.
2432 /// \code{.js}
2433 /// string1 = "foo";
2434 /// string2 = 'bar';
2435 /// \endcode
2436 JSQS_Leave,
2437 /// Always use single quotes.
2438 /// \code{.js}
2439 /// string1 = 'foo';
2440 /// string2 = 'bar';
2441 /// \endcode
2442 JSQS_Single,
2443 /// Always use double quotes.
2444 /// \code{.js}
2445 /// string1 = "foo";
2446 /// string2 = "bar";
2447 /// \endcode
2448 JSQS_Double
2449 };
2450
2451 /// The JavaScriptQuoteStyle to use for JavaScript strings.
2452 JavaScriptQuoteStyle JavaScriptQuotes;
2453
2454 // clang-format off
2455 /// Whether to wrap JavaScript import/export statements.
2456 /// \code{.js}
2457 /// true:
2458 /// import {
2459 /// VeryLongImportsAreAnnoying,
2460 /// VeryLongImportsAreAnnoying,
2461 /// VeryLongImportsAreAnnoying,
2462 /// } from 'some/module.js'
2463 ///
2464 /// false:
2465 /// import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
2466 /// \endcode
2467 bool JavaScriptWrapImports;
2468 // clang-format on
2469
2470 /// If true, the empty line at the start of blocks is kept.
2471 /// \code
2472 /// true: false:
2473 /// if (foo) { vs. if (foo) {
2474 /// bar();
2475 /// bar(); }
2476 /// }
2477 /// \endcode
2478 bool KeepEmptyLinesAtTheStartOfBlocks;
2479
2480 /// Supported languages.
2481 ///
2482 /// When stored in a configuration file, specifies the language, that the
2483 /// configuration targets. When passed to the ``reformat()`` function, enables
2484 /// syntax features specific to the language.
2485 enum LanguageKind : unsigned char {
2486 /// Do not use.
2487 LK_None,
2488 /// Should be used for C, C++.
2489 LK_Cpp,
2490 /// Should be used for C#.
2491 LK_CSharp,
2492 /// Should be used for Java.
2493 LK_Java,
2494 /// Should be used for JavaScript.
2495 LK_JavaScript,
2496 /// Should be used for JSON.
2497 LK_Json,
2498 /// Should be used for Objective-C, Objective-C++.
2499 LK_ObjC,
2500 /// Should be used for Protocol Buffers
2501 /// (https://developers.google.com/protocol-buffers/).
2502 LK_Proto,
2503 /// Should be used for TableGen code.
2504 LK_TableGen,
2505 /// Should be used for Protocol Buffer messages in text format
2506 /// (https://developers.google.com/protocol-buffers/).
2507 LK_TextProto
2508 };
isCppFormatStyle2509 bool isCpp() const { return Language == LK_Cpp || Language == LK_ObjC; }
isCSharpFormatStyle2510 bool isCSharp() const { return Language == LK_CSharp; }
isJsonFormatStyle2511 bool isJson() const { return Language == LK_Json; }
2512
2513 /// Language, this format style is targeted at.
2514 LanguageKind Language;
2515
2516 /// Indentation logic for lambda bodies.
2517 enum LambdaBodyIndentationKind : unsigned char {
2518 /// Align lambda body relative to the lambda signature. This is the default.
2519 /// \code
2520 /// someMethod(
2521 /// [](SomeReallyLongLambdaSignatureArgument foo) {
2522 /// return;
2523 /// });
2524 /// \endcode
2525 LBI_Signature,
2526 /// Align lambda body relative to the indentation level of the outer scope
2527 /// the lambda signature resides in.
2528 /// \code
2529 /// someMethod(
2530 /// [](SomeReallyLongLambdaSignatureArgument foo) {
2531 /// return;
2532 /// });
2533 /// \endcode
2534 LBI_OuterScope,
2535 };
2536
2537 /// The indentation style of lambda bodies. ``Signature`` (the default)
2538 /// causes the lambda body to be indented one additional level relative to
2539 /// the indentation level of the signature. ``OuterScope`` forces the lambda
2540 /// body to be indented one additional level relative to the parent scope
2541 /// containing the lambda signature. For callback-heavy code, it may improve
2542 /// readability to have the signature indented two levels and to use
2543 /// ``OuterScope``. The KJ style guide requires ``OuterScope``.
2544 /// `KJ style guide
2545 /// <https://github.com/capnproto/capnproto/blob/master/kjdoc/style-guide.md>`_
2546 LambdaBodyIndentationKind LambdaBodyIndentation;
2547
2548 /// A regular expression matching macros that start a block.
2549 /// \code
2550 /// # With:
2551 /// MacroBlockBegin: "^NS_MAP_BEGIN|\
2552 /// NS_TABLE_HEAD$"
2553 /// MacroBlockEnd: "^\
2554 /// NS_MAP_END|\
2555 /// NS_TABLE_.*_END$"
2556 ///
2557 /// NS_MAP_BEGIN
2558 /// foo();
2559 /// NS_MAP_END
2560 ///
2561 /// NS_TABLE_HEAD
2562 /// bar();
2563 /// NS_TABLE_FOO_END
2564 ///
2565 /// # Without:
2566 /// NS_MAP_BEGIN
2567 /// foo();
2568 /// NS_MAP_END
2569 ///
2570 /// NS_TABLE_HEAD
2571 /// bar();
2572 /// NS_TABLE_FOO_END
2573 /// \endcode
2574 std::string MacroBlockBegin;
2575
2576 /// A regular expression matching macros that end a block.
2577 std::string MacroBlockEnd;
2578
2579 /// The maximum number of consecutive empty lines to keep.
2580 /// \code
2581 /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
2582 /// int f() { int f() {
2583 /// int = 1; int i = 1;
2584 /// i = foo();
2585 /// i = foo(); return i;
2586 /// }
2587 /// return i;
2588 /// }
2589 /// \endcode
2590 unsigned MaxEmptyLinesToKeep;
2591
2592 /// Different ways to indent namespace contents.
2593 enum NamespaceIndentationKind : unsigned char {
2594 /// Don't indent in namespaces.
2595 /// \code
2596 /// namespace out {
2597 /// int i;
2598 /// namespace in {
2599 /// int i;
2600 /// }
2601 /// }
2602 /// \endcode
2603 NI_None,
2604 /// Indent only in inner namespaces (nested in other namespaces).
2605 /// \code
2606 /// namespace out {
2607 /// int i;
2608 /// namespace in {
2609 /// int i;
2610 /// }
2611 /// }
2612 /// \endcode
2613 NI_Inner,
2614 /// Indent in all namespaces.
2615 /// \code
2616 /// namespace out {
2617 /// int i;
2618 /// namespace in {
2619 /// int i;
2620 /// }
2621 /// }
2622 /// \endcode
2623 NI_All
2624 };
2625
2626 /// The indentation used for namespaces.
2627 NamespaceIndentationKind NamespaceIndentation;
2628
2629 /// Controls bin-packing Objective-C protocol conformance list
2630 /// items into as few lines as possible when they go over ``ColumnLimit``.
2631 ///
2632 /// If ``Auto`` (the default), delegates to the value in
2633 /// ``BinPackParameters``. If that is ``true``, bin-packs Objective-C
2634 /// protocol conformance list items into as few lines as possible
2635 /// whenever they go over ``ColumnLimit``.
2636 ///
2637 /// If ``Always``, always bin-packs Objective-C protocol conformance
2638 /// list items into as few lines as possible whenever they go over
2639 /// ``ColumnLimit``.
2640 ///
2641 /// If ``Never``, lays out Objective-C protocol conformance list items
2642 /// onto individual lines whenever they go over ``ColumnLimit``.
2643 ///
2644 /// \code{.objc}
2645 /// Always (or Auto, if BinPackParameters=true):
2646 /// @interface ccccccccccccc () <
2647 /// ccccccccccccc, ccccccccccccc,
2648 /// ccccccccccccc, ccccccccccccc> {
2649 /// }
2650 ///
2651 /// Never (or Auto, if BinPackParameters=false):
2652 /// @interface ddddddddddddd () <
2653 /// ddddddddddddd,
2654 /// ddddddddddddd,
2655 /// ddddddddddddd,
2656 /// ddddddddddddd> {
2657 /// }
2658 /// \endcode
2659 BinPackStyle ObjCBinPackProtocolList;
2660
2661 /// The number of characters to use for indentation of ObjC blocks.
2662 /// \code{.objc}
2663 /// ObjCBlockIndentWidth: 4
2664 ///
2665 /// [operation setCompletionBlock:^{
2666 /// [self onOperationDone];
2667 /// }];
2668 /// \endcode
2669 unsigned ObjCBlockIndentWidth;
2670
2671 /// Add a space after ``@property`` in Objective-C, i.e. use
2672 /// ``@property (readonly)`` instead of ``@property(readonly)``.
2673 bool ObjCSpaceAfterProperty;
2674
2675 /// Break parameters list into lines when there is nested block
2676 /// parameters in a function call.
2677 /// \code
2678 /// false:
2679 /// - (void)_aMethod
2680 /// {
2681 /// [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
2682 /// *u, NSNumber *v) {
2683 /// u = c;
2684 /// }]
2685 /// }
2686 /// true:
2687 /// - (void)_aMethod
2688 /// {
2689 /// [self.test1 t:self
2690 /// w:self
2691 /// callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
2692 /// u = c;
2693 /// }]
2694 /// }
2695 /// \endcode
2696 bool ObjCBreakBeforeNestedBlockParam;
2697
2698 /// Add a space in front of an Objective-C protocol list, i.e. use
2699 /// ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
2700 bool ObjCSpaceBeforeProtocolList;
2701
2702 /// The penalty for breaking around an assignment operator.
2703 unsigned PenaltyBreakAssignment;
2704
2705 /// The penalty for breaking a function call after ``call(``.
2706 unsigned PenaltyBreakBeforeFirstCallParameter;
2707
2708 /// The penalty for each line break introduced inside a comment.
2709 unsigned PenaltyBreakComment;
2710
2711 /// The penalty for breaking before the first ``<<``.
2712 unsigned PenaltyBreakFirstLessLess;
2713
2714 /// The penalty for each line break introduced inside a string literal.
2715 unsigned PenaltyBreakString;
2716
2717 /// The penalty for breaking after template declaration.
2718 unsigned PenaltyBreakTemplateDeclaration;
2719
2720 /// The penalty for each character outside of the column limit.
2721 unsigned PenaltyExcessCharacter;
2722
2723 /// Penalty for putting the return type of a function onto its own
2724 /// line.
2725 unsigned PenaltyReturnTypeOnItsOwnLine;
2726
2727 /// Penalty for each character of whitespace indentation
2728 /// (counted relative to leading non-whitespace column).
2729 unsigned PenaltyIndentedWhitespace;
2730
2731 /// The ``&``, ``&&`` and ``*`` alignment style.
2732 enum PointerAlignmentStyle : unsigned char {
2733 /// Align pointer to the left.
2734 /// \code
2735 /// int* a;
2736 /// \endcode
2737 PAS_Left,
2738 /// Align pointer to the right.
2739 /// \code
2740 /// int *a;
2741 /// \endcode
2742 PAS_Right,
2743 /// Align pointer in the middle.
2744 /// \code
2745 /// int * a;
2746 /// \endcode
2747 PAS_Middle
2748 };
2749
2750 /// Pointer and reference alignment style.
2751 PointerAlignmentStyle PointerAlignment;
2752
2753 /// The number of columns to use for indentation of preprocessor statements.
2754 /// When set to -1 (default) ``IndentWidth`` is used also for preprocessor
2755 /// statements.
2756 /// \code
2757 /// PPIndentWidth: 1
2758 ///
2759 /// #ifdef __linux__
2760 /// # define FOO
2761 /// #else
2762 /// # define BAR
2763 /// #endif
2764 /// \endcode
2765 int PPIndentWidth;
2766
2767 /// See documentation of ``RawStringFormats``.
2768 struct RawStringFormat {
2769 /// The language of this raw string.
2770 LanguageKind Language;
2771 /// A list of raw string delimiters that match this language.
2772 std::vector<std::string> Delimiters;
2773 /// A list of enclosing function names that match this language.
2774 std::vector<std::string> EnclosingFunctions;
2775 /// The canonical delimiter for this language.
2776 std::string CanonicalDelimiter;
2777 /// The style name on which this raw string format is based on.
2778 /// If not specified, the raw string format is based on the style that this
2779 /// format is based on.
2780 std::string BasedOnStyle;
2781 bool operator==(const RawStringFormat &Other) const {
2782 return Language == Other.Language && Delimiters == Other.Delimiters &&
2783 EnclosingFunctions == Other.EnclosingFunctions &&
2784 CanonicalDelimiter == Other.CanonicalDelimiter &&
2785 BasedOnStyle == Other.BasedOnStyle;
2786 }
2787 };
2788
2789 /// Defines hints for detecting supported languages code blocks in raw
2790 /// strings.
2791 ///
2792 /// A raw string with a matching delimiter or a matching enclosing function
2793 /// name will be reformatted assuming the specified language based on the
2794 /// style for that language defined in the .clang-format file. If no style has
2795 /// been defined in the .clang-format file for the specific language, a
2796 /// predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
2797 /// found, the formatting is based on llvm style. A matching delimiter takes
2798 /// precedence over a matching enclosing function name for determining the
2799 /// language of the raw string contents.
2800 ///
2801 /// If a canonical delimiter is specified, occurrences of other delimiters for
2802 /// the same language will be updated to the canonical if possible.
2803 ///
2804 /// There should be at most one specification per language and each delimiter
2805 /// and enclosing function should not occur in multiple specifications.
2806 ///
2807 /// To configure this in the .clang-format file, use:
2808 /// \code{.yaml}
2809 /// RawStringFormats:
2810 /// - Language: TextProto
2811 /// Delimiters:
2812 /// - 'pb'
2813 /// - 'proto'
2814 /// EnclosingFunctions:
2815 /// - 'PARSE_TEXT_PROTO'
2816 /// BasedOnStyle: google
2817 /// - Language: Cpp
2818 /// Delimiters:
2819 /// - 'cc'
2820 /// - 'cpp'
2821 /// BasedOnStyle: llvm
2822 /// CanonicalDelimiter: 'cc'
2823 /// \endcode
2824 std::vector<RawStringFormat> RawStringFormats;
2825
2826 /// \brief The ``&`` and ``&&`` alignment style.
2827 enum ReferenceAlignmentStyle {
2828 /// Align reference like ``PointerAlignment``.
2829 RAS_Pointer,
2830 /// Align reference to the left.
2831 /// \code
2832 /// int& a;
2833 /// \endcode
2834 RAS_Left,
2835 /// Align reference to the right.
2836 /// \code
2837 /// int &a;
2838 /// \endcode
2839 RAS_Right,
2840 /// Align reference in the middle.
2841 /// \code
2842 /// int & a;
2843 /// \endcode
2844 RAS_Middle
2845 };
2846
2847 /// \brief Reference alignment style (overrides ``PointerAlignment`` for
2848 /// references).
2849 ReferenceAlignmentStyle ReferenceAlignment;
2850
2851 // clang-format off
2852 /// If ``true``, clang-format will attempt to re-flow comments.
2853 /// \code
2854 /// false:
2855 /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
2856 /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
2857 ///
2858 /// true:
2859 /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
2860 /// // information
2861 /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
2862 /// * information */
2863 /// \endcode
2864 bool ReflowComments;
2865 // clang-format on
2866
2867 /// The maximal number of unwrapped lines that a short namespace spans.
2868 /// Defaults to 1.
2869 ///
2870 /// This determines the maximum length of short namespaces by counting
2871 /// unwrapped lines (i.e. containing neither opening nor closing
2872 /// namespace brace) and makes "FixNamespaceComments" omit adding
2873 /// end comments for those.
2874 /// \code
2875 /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
2876 /// namespace a { namespace a {
2877 /// int foo; int foo;
2878 /// } } // namespace a
2879 ///
2880 /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
2881 /// namespace b { namespace b {
2882 /// int foo; int foo;
2883 /// int bar; int bar;
2884 /// } // namespace b } // namespace b
2885 /// \endcode
2886 unsigned ShortNamespaceLines;
2887
2888 /// Include sorting options.
2889 enum SortIncludesOptions : unsigned char {
2890 /// Includes are never sorted.
2891 /// \code
2892 /// #include "B/A.h"
2893 /// #include "A/B.h"
2894 /// #include "a/b.h"
2895 /// #include "A/b.h"
2896 /// #include "B/a.h"
2897 /// \endcode
2898 SI_Never,
2899 /// Includes are sorted in an ASCIIbetical or case sensitive fashion.
2900 /// \code
2901 /// #include "A/B.h"
2902 /// #include "A/b.h"
2903 /// #include "B/A.h"
2904 /// #include "B/a.h"
2905 /// #include "a/b.h"
2906 /// \endcode
2907 SI_CaseSensitive,
2908 /// Includes are sorted in an alphabetical or case insensitive fashion.
2909 /// \code
2910 /// #include "A/B.h"
2911 /// #include "A/b.h"
2912 /// #include "a/b.h"
2913 /// #include "B/A.h"
2914 /// #include "B/a.h"
2915 /// \endcode
2916 SI_CaseInsensitive,
2917 };
2918
2919 /// Controls if and how clang-format will sort ``#includes``.
2920 /// If ``Never``, includes are never sorted.
2921 /// If ``CaseInsensitive``, includes are sorted in an ASCIIbetical or case
2922 /// insensitive fashion.
2923 /// If ``CaseSensitive``, includes are sorted in an alphabetical or case
2924 /// sensitive fashion.
2925 SortIncludesOptions SortIncludes;
2926
2927 /// Position for Java Static imports.
2928 enum SortJavaStaticImportOptions : unsigned char {
2929 /// Static imports are placed before non-static imports.
2930 /// \code{.java}
2931 /// import static org.example.function1;
2932 ///
2933 /// import org.example.ClassA;
2934 /// \endcode
2935 SJSIO_Before,
2936 /// Static imports are placed after non-static imports.
2937 /// \code{.java}
2938 /// import org.example.ClassA;
2939 ///
2940 /// import static org.example.function1;
2941 /// \endcode
2942 SJSIO_After,
2943 };
2944
2945 /// When sorting Java imports, by default static imports are placed before
2946 /// non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
2947 /// static imports are placed after non-static imports.
2948 SortJavaStaticImportOptions SortJavaStaticImport;
2949
2950 /// If ``true``, clang-format will sort using declarations.
2951 ///
2952 /// The order of using declarations is defined as follows:
2953 /// Split the strings by "::" and discard any initial empty strings. The last
2954 /// element of each list is a non-namespace name; all others are namespace
2955 /// names. Sort the lists of names lexicographically, where the sort order of
2956 /// individual names is that all non-namespace names come before all namespace
2957 /// names, and within those groups, names are in case-insensitive
2958 /// lexicographic order.
2959 /// \code
2960 /// false: true:
2961 /// using std::cout; vs. using std::cin;
2962 /// using std::cin; using std::cout;
2963 /// \endcode
2964 bool SortUsingDeclarations;
2965
2966 /// If ``true``, a space is inserted after C style casts.
2967 /// \code
2968 /// true: false:
2969 /// (int) i; vs. (int)i;
2970 /// \endcode
2971 bool SpaceAfterCStyleCast;
2972
2973 /// If ``true``, a space is inserted after the logical not operator (``!``).
2974 /// \code
2975 /// true: false:
2976 /// ! someExpression(); vs. !someExpression();
2977 /// \endcode
2978 bool SpaceAfterLogicalNot;
2979
2980 /// If \c true, a space will be inserted after the 'template' keyword.
2981 /// \code
2982 /// true: false:
2983 /// template <int> void foo(); vs. template<int> void foo();
2984 /// \endcode
2985 bool SpaceAfterTemplateKeyword;
2986
2987 /// Different ways to put a space before opening parentheses.
2988 enum SpaceAroundPointerQualifiersStyle : unsigned char {
2989 /// Don't ensure spaces around pointer qualifiers and use PointerAlignment
2990 /// instead.
2991 /// \code
2992 /// PointerAlignment: Left PointerAlignment: Right
2993 /// void* const* x = NULL; vs. void *const *x = NULL;
2994 /// \endcode
2995 SAPQ_Default,
2996 /// Ensure that there is a space before pointer qualifiers.
2997 /// \code
2998 /// PointerAlignment: Left PointerAlignment: Right
2999 /// void* const* x = NULL; vs. void * const *x = NULL;
3000 /// \endcode
3001 SAPQ_Before,
3002 /// Ensure that there is a space after pointer qualifiers.
3003 /// \code
3004 /// PointerAlignment: Left PointerAlignment: Right
3005 /// void* const * x = NULL; vs. void *const *x = NULL;
3006 /// \endcode
3007 SAPQ_After,
3008 /// Ensure that there is a space both before and after pointer qualifiers.
3009 /// \code
3010 /// PointerAlignment: Left PointerAlignment: Right
3011 /// void* const * x = NULL; vs. void * const *x = NULL;
3012 /// \endcode
3013 SAPQ_Both,
3014 };
3015
3016 /// Defines in which cases to put a space before or after pointer qualifiers
3017 SpaceAroundPointerQualifiersStyle SpaceAroundPointerQualifiers;
3018
3019 /// If ``false``, spaces will be removed before assignment operators.
3020 /// \code
3021 /// true: false:
3022 /// int a = 5; vs. int a= 5;
3023 /// a += 42; a+= 42;
3024 /// \endcode
3025 bool SpaceBeforeAssignmentOperators;
3026
3027 /// If ``false``, spaces will be removed before case colon.
3028 /// \code
3029 /// true: false
3030 /// switch (x) { vs. switch (x) {
3031 /// case 1 : break; case 1: break;
3032 /// } }
3033 /// \endcode
3034 bool SpaceBeforeCaseColon;
3035
3036 /// If ``true``, a space will be inserted before a C++11 braced list
3037 /// used to initialize an object (after the preceding identifier or type).
3038 /// \code
3039 /// true: false:
3040 /// Foo foo { bar }; vs. Foo foo{ bar };
3041 /// Foo {}; Foo{};
3042 /// vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
3043 /// new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
3044 /// \endcode
3045 bool SpaceBeforeCpp11BracedList;
3046
3047 /// If ``false``, spaces will be removed before constructor initializer
3048 /// colon.
3049 /// \code
3050 /// true: false:
3051 /// Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
3052 /// \endcode
3053 bool SpaceBeforeCtorInitializerColon;
3054
3055 /// If ``false``, spaces will be removed before inheritance colon.
3056 /// \code
3057 /// true: false:
3058 /// class Foo : Bar {} vs. class Foo: Bar {}
3059 /// \endcode
3060 bool SpaceBeforeInheritanceColon;
3061
3062 /// Different ways to put a space before opening parentheses.
3063 enum SpaceBeforeParensOptions : unsigned char {
3064 /// Never put a space before opening parentheses.
3065 /// \code
3066 /// void f() {
3067 /// if(true) {
3068 /// f();
3069 /// }
3070 /// }
3071 /// \endcode
3072 SBPO_Never,
3073 /// Put a space before opening parentheses only after control statement
3074 /// keywords (``for/if/while...``).
3075 /// \code
3076 /// void f() {
3077 /// if (true) {
3078 /// f();
3079 /// }
3080 /// }
3081 /// \endcode
3082 SBPO_ControlStatements,
3083 /// Same as ``SBPO_ControlStatements`` except this option doesn't apply to
3084 /// ForEach and If macros. This is useful in projects where ForEach/If
3085 /// macros are treated as function calls instead of control statements.
3086 /// ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
3087 /// backward compatability.
3088 /// \code
3089 /// void f() {
3090 /// Q_FOREACH(...) {
3091 /// f();
3092 /// }
3093 /// }
3094 /// \endcode
3095 SBPO_ControlStatementsExceptControlMacros,
3096 /// Put a space before opening parentheses only if the parentheses are not
3097 /// empty i.e. '()'
3098 /// \code
3099 /// void() {
3100 /// if (true) {
3101 /// f();
3102 /// g (x, y, z);
3103 /// }
3104 /// }
3105 /// \endcode
3106 SBPO_NonEmptyParentheses,
3107 /// Always put a space before opening parentheses, except when it's
3108 /// prohibited by the syntax rules (in function-like macro definitions) or
3109 /// when determined by other style rules (after unary operators, opening
3110 /// parentheses, etc.)
3111 /// \code
3112 /// void f () {
3113 /// if (true) {
3114 /// f ();
3115 /// }
3116 /// }
3117 /// \endcode
3118 SBPO_Always
3119 };
3120
3121 /// Defines in which cases to put a space before opening parentheses.
3122 SpaceBeforeParensOptions SpaceBeforeParens;
3123
3124 /// If ``false``, spaces will be removed before range-based for loop
3125 /// colon.
3126 /// \code
3127 /// true: false:
3128 /// for (auto v : values) {} vs. for(auto v: values) {}
3129 /// \endcode
3130 bool SpaceBeforeRangeBasedForLoopColon;
3131
3132 /// If ``true``, spaces will be inserted into ``{}``.
3133 /// \code
3134 /// true: false:
3135 /// void f() { } vs. void f() {}
3136 /// while (true) { } while (true) {}
3137 /// \endcode
3138 bool SpaceInEmptyBlock;
3139
3140 /// If ``true``, spaces may be inserted into ``()``.
3141 /// \code
3142 /// true: false:
3143 /// void f( ) { vs. void f() {
3144 /// int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
3145 /// if (true) { if (true) {
3146 /// f( ); f();
3147 /// } }
3148 /// } }
3149 /// \endcode
3150 bool SpaceInEmptyParentheses;
3151
3152 /// The number of spaces before trailing line comments
3153 /// (``//`` - comments).
3154 ///
3155 /// This does not affect trailing block comments (``/*`` - comments) as
3156 /// those commonly have different usage patterns and a number of special
3157 /// cases.
3158 /// \code
3159 /// SpacesBeforeTrailingComments: 3
3160 /// void f() {
3161 /// if (true) { // foo1
3162 /// f(); // bar
3163 /// } // foo
3164 /// }
3165 /// \endcode
3166 unsigned SpacesBeforeTrailingComments;
3167
3168 /// Styles for adding spacing after ``<`` and before ``>`
3169 /// in template argument lists.
3170 enum SpacesInAnglesStyle : unsigned char {
3171 /// Remove spaces after ``<`` and before ``>``.
3172 /// \code
3173 /// static_cast<int>(arg);
3174 /// std::function<void(int)> fct;
3175 /// \endcode
3176 SIAS_Never,
3177 /// Add spaces after ``<`` and before ``>``.
3178 /// \code
3179 /// static_cast< int >(arg);
3180 /// std::function< void(int) > fct;
3181 /// \endcode
3182 SIAS_Always,
3183 /// Keep a single space after ``<`` and before ``>`` if any spaces were
3184 /// present. Option ``Standard: Cpp03`` takes precedence.
3185 SIAS_Leave
3186 };
3187 /// The SpacesInAnglesStyle to use for template argument lists.
3188 SpacesInAnglesStyle SpacesInAngles;
3189
3190 /// If ``true``, spaces will be inserted around if/for/switch/while
3191 /// conditions.
3192 /// \code
3193 /// true: false:
3194 /// if ( a ) { ... } vs. if (a) { ... }
3195 /// while ( i < 5 ) { ... } while (i < 5) { ... }
3196 /// \endcode
3197 bool SpacesInConditionalStatement;
3198
3199 /// If ``true``, spaces are inserted inside container literals (e.g.
3200 /// ObjC and Javascript array and dict literals).
3201 /// \code{.js}
3202 /// true: false:
3203 /// var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
3204 /// f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
3205 /// \endcode
3206 bool SpacesInContainerLiterals;
3207
3208 /// If ``true``, spaces may be inserted into C style casts.
3209 /// \code
3210 /// true: false:
3211 /// x = ( int32 )y vs. x = (int32)y
3212 /// \endcode
3213 bool SpacesInCStyleCastParentheses;
3214
3215 /// Control of spaces within a single line comment
3216 struct SpacesInLineComment {
3217 /// The minimum number of spaces at the start of the comment.
3218 unsigned Minimum;
3219 /// The maximum number of spaces at the start of the comment.
3220 unsigned Maximum;
3221 };
3222
3223 /// How many spaces are allowed at the start of a line comment. To disable the
3224 /// maximum set it to ``-1``, apart from that the maximum takes precedence
3225 /// over the minimum.
3226 /// \code Minimum = 1 Maximum = -1
3227 /// // One space is forced
3228 ///
3229 /// // but more spaces are possible
3230 ///
3231 /// Minimum = 0
3232 /// Maximum = 0
3233 /// //Forces to start every comment directly after the slashes
3234 /// \endcode
3235 ///
3236 /// Note that in line comment sections the relative indent of the subsequent
3237 /// lines is kept, that means the following:
3238 /// \code
3239 /// before: after:
3240 /// Minimum: 1
3241 /// //if (b) { // if (b) {
3242 /// // return true; // return true;
3243 /// //} // }
3244 ///
3245 /// Maximum: 0
3246 /// /// List: ///List:
3247 /// /// - Foo /// - Foo
3248 /// /// - Bar /// - Bar
3249 /// \endcode
3250 SpacesInLineComment SpacesInLineCommentPrefix;
3251
3252 /// If ``true``, spaces will be inserted after ``(`` and before ``)``.
3253 /// \code
3254 /// true: false:
3255 /// t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
3256 /// \endcode
3257 bool SpacesInParentheses;
3258
3259 /// If ``true``, spaces will be inserted after ``[`` and before ``]``.
3260 /// Lambdas without arguments or unspecified size array declarations will not
3261 /// be affected.
3262 /// \code
3263 /// true: false:
3264 /// int a[ 5 ]; vs. int a[5];
3265 /// std::unique_ptr<int[]> foo() {} // Won't be affected
3266 /// \endcode
3267 bool SpacesInSquareBrackets;
3268
3269 /// If ``true``, spaces will be before ``[``.
3270 /// Lambdas will not be affected. Only the first ``[`` will get a space added.
3271 /// \code
3272 /// true: false:
3273 /// int a [5]; vs. int a[5];
3274 /// int a [5][5]; vs. int a[5][5];
3275 /// \endcode
3276 bool SpaceBeforeSquareBrackets;
3277
3278 /// Styles for adding spacing around ``:`` in bitfield definitions.
3279 enum BitFieldColonSpacingStyle : unsigned char {
3280 /// Add one space on each side of the ``:``
3281 /// \code
3282 /// unsigned bf : 2;
3283 /// \endcode
3284 BFCS_Both,
3285 /// Add no space around the ``:`` (except when needed for
3286 /// ``AlignConsecutiveBitFields``).
3287 /// \code
3288 /// unsigned bf:2;
3289 /// \endcode
3290 BFCS_None,
3291 /// Add space before the ``:`` only
3292 /// \code
3293 /// unsigned bf :2;
3294 /// \endcode
3295 BFCS_Before,
3296 /// Add space after the ``:`` only (space may be added before if
3297 /// needed for ``AlignConsecutiveBitFields``).
3298 /// \code
3299 /// unsigned bf: 2;
3300 /// \endcode
3301 BFCS_After
3302 };
3303 /// The BitFieldColonSpacingStyle to use for bitfields.
3304 BitFieldColonSpacingStyle BitFieldColonSpacing;
3305
3306 /// Supported language standards for parsing and formatting C++ constructs.
3307 /// \code
3308 /// Latest: vector<set<int>>
3309 /// c++03 vs. vector<set<int> >
3310 /// \endcode
3311 ///
3312 /// The correct way to spell a specific language version is e.g. ``c++11``.
3313 /// The historical aliases ``Cpp03`` and ``Cpp11`` are deprecated.
3314 enum LanguageStandard : unsigned char {
3315 /// Parse and format as C++03.
3316 /// ``Cpp03`` is a deprecated alias for ``c++03``
3317 LS_Cpp03, // c++03
3318 /// Parse and format as C++11.
3319 LS_Cpp11, // c++11
3320 /// Parse and format as C++14.
3321 LS_Cpp14, // c++14
3322 /// Parse and format as C++17.
3323 LS_Cpp17, // c++17
3324 /// Parse and format as C++20.
3325 LS_Cpp20, // c++20
3326 /// Parse and format using the latest supported language version.
3327 /// ``Cpp11`` is a deprecated alias for ``Latest``
3328 LS_Latest,
3329 /// Automatic detection based on the input.
3330 LS_Auto,
3331 };
3332
3333 /// Parse and format C++ constructs compatible with this standard.
3334 /// \code
3335 /// c++03: latest:
3336 /// vector<set<int> > x; vs. vector<set<int>> x;
3337 /// \endcode
3338 LanguageStandard Standard;
3339
3340 /// Macros which are ignored in front of a statement, as if they were an
3341 /// attribute. So that they are not parsed as identifier, for example for Qts
3342 /// emit.
3343 /// \code
3344 /// AlignConsecutiveDeclarations: true
3345 /// StatementAttributeLikeMacros: []
3346 /// unsigned char data = 'x';
3347 /// emit signal(data); // This is parsed as variable declaration.
3348 ///
3349 /// AlignConsecutiveDeclarations: true
3350 /// StatementAttributeLikeMacros: [emit]
3351 /// unsigned char data = 'x';
3352 /// emit signal(data); // Now it's fine again.
3353 /// \endcode
3354 std::vector<std::string> StatementAttributeLikeMacros;
3355
3356 /// The number of columns used for tab stops.
3357 unsigned TabWidth;
3358
3359 /// Different ways to use tab in formatting.
3360 enum UseTabStyle : unsigned char {
3361 /// Never use tab.
3362 UT_Never,
3363 /// Use tabs only for indentation.
3364 UT_ForIndentation,
3365 /// Fill all leading whitespace with tabs, and use spaces for alignment that
3366 /// appears within a line (e.g. consecutive assignments and declarations).
3367 UT_ForContinuationAndIndentation,
3368 /// Use tabs for line continuation and indentation, and spaces for
3369 /// alignment.
3370 UT_AlignWithSpaces,
3371 /// Use tabs whenever we need to fill whitespace that spans at least from
3372 /// one tab stop to the next one.
3373 UT_Always
3374 };
3375
3376 /// \brief Use ``\r\n`` instead of ``\n`` for line breaks.
3377 /// Also used as fallback if ``DeriveLineEnding`` is true.
3378 bool UseCRLF;
3379
3380 /// The way to use tab characters in the resulting file.
3381 UseTabStyle UseTab;
3382
3383 bool operator==(const FormatStyle &R) const {
3384 return AccessModifierOffset == R.AccessModifierOffset &&
3385 AlignAfterOpenBracket == R.AlignAfterOpenBracket &&
3386 AlignArrayOfStructures == R.AlignArrayOfStructures &&
3387 AlignConsecutiveAssignments == R.AlignConsecutiveAssignments &&
3388 AlignConsecutiveBitFields == R.AlignConsecutiveBitFields &&
3389 AlignConsecutiveDeclarations == R.AlignConsecutiveDeclarations &&
3390 AlignConsecutiveMacros == R.AlignConsecutiveMacros &&
3391 AlignEscapedNewlines == R.AlignEscapedNewlines &&
3392 AlignOperands == R.AlignOperands &&
3393 AlignTrailingComments == R.AlignTrailingComments &&
3394 AllowAllArgumentsOnNextLine == R.AllowAllArgumentsOnNextLine &&
3395 AllowAllConstructorInitializersOnNextLine ==
3396 R.AllowAllConstructorInitializersOnNextLine &&
3397 AllowAllParametersOfDeclarationOnNextLine ==
3398 R.AllowAllParametersOfDeclarationOnNextLine &&
3399 AllowShortEnumsOnASingleLine == R.AllowShortEnumsOnASingleLine &&
3400 AllowShortBlocksOnASingleLine == R.AllowShortBlocksOnASingleLine &&
3401 AllowShortCaseLabelsOnASingleLine ==
3402 R.AllowShortCaseLabelsOnASingleLine &&
3403 AllowShortFunctionsOnASingleLine ==
3404 R.AllowShortFunctionsOnASingleLine &&
3405 AllowShortIfStatementsOnASingleLine ==
3406 R.AllowShortIfStatementsOnASingleLine &&
3407 AllowShortLambdasOnASingleLine == R.AllowShortLambdasOnASingleLine &&
3408 AllowShortLoopsOnASingleLine == R.AllowShortLoopsOnASingleLine &&
3409 AlwaysBreakAfterReturnType == R.AlwaysBreakAfterReturnType &&
3410 AlwaysBreakBeforeMultilineStrings ==
3411 R.AlwaysBreakBeforeMultilineStrings &&
3412 AlwaysBreakTemplateDeclarations ==
3413 R.AlwaysBreakTemplateDeclarations &&
3414 AttributeMacros == R.AttributeMacros &&
3415 BinPackArguments == R.BinPackArguments &&
3416 BinPackParameters == R.BinPackParameters &&
3417 BreakBeforeBinaryOperators == R.BreakBeforeBinaryOperators &&
3418 BreakBeforeBraces == R.BreakBeforeBraces &&
3419 BreakBeforeConceptDeclarations == R.BreakBeforeConceptDeclarations &&
3420 BreakBeforeTernaryOperators == R.BreakBeforeTernaryOperators &&
3421 BreakConstructorInitializers == R.BreakConstructorInitializers &&
3422 CompactNamespaces == R.CompactNamespaces &&
3423 BreakAfterJavaFieldAnnotations == R.BreakAfterJavaFieldAnnotations &&
3424 BreakStringLiterals == R.BreakStringLiterals &&
3425 ColumnLimit == R.ColumnLimit && CommentPragmas == R.CommentPragmas &&
3426 BreakInheritanceList == R.BreakInheritanceList &&
3427 ConstructorInitializerAllOnOneLineOrOnePerLine ==
3428 R.ConstructorInitializerAllOnOneLineOrOnePerLine &&
3429 ConstructorInitializerIndentWidth ==
3430 R.ConstructorInitializerIndentWidth &&
3431 ContinuationIndentWidth == R.ContinuationIndentWidth &&
3432 Cpp11BracedListStyle == R.Cpp11BracedListStyle &&
3433 DeriveLineEnding == R.DeriveLineEnding &&
3434 DerivePointerAlignment == R.DerivePointerAlignment &&
3435 DisableFormat == R.DisableFormat &&
3436 EmptyLineAfterAccessModifier == R.EmptyLineAfterAccessModifier &&
3437 EmptyLineBeforeAccessModifier == R.EmptyLineBeforeAccessModifier &&
3438 ExperimentalAutoDetectBinPacking ==
3439 R.ExperimentalAutoDetectBinPacking &&
3440 FixNamespaceComments == R.FixNamespaceComments &&
3441 ForEachMacros == R.ForEachMacros &&
3442 IncludeStyle.IncludeBlocks == R.IncludeStyle.IncludeBlocks &&
3443 IncludeStyle.IncludeCategories == R.IncludeStyle.IncludeCategories &&
3444 IncludeStyle.IncludeIsMainRegex ==
3445 R.IncludeStyle.IncludeIsMainRegex &&
3446 IncludeStyle.IncludeIsMainSourceRegex ==
3447 R.IncludeStyle.IncludeIsMainSourceRegex &&
3448 IndentAccessModifiers == R.IndentAccessModifiers &&
3449 IndentCaseLabels == R.IndentCaseLabels &&
3450 IndentCaseBlocks == R.IndentCaseBlocks &&
3451 IndentGotoLabels == R.IndentGotoLabels &&
3452 IndentPPDirectives == R.IndentPPDirectives &&
3453 IndentExternBlock == R.IndentExternBlock &&
3454 IndentRequires == R.IndentRequires && IndentWidth == R.IndentWidth &&
3455 Language == R.Language &&
3456 IndentWrappedFunctionNames == R.IndentWrappedFunctionNames &&
3457 JavaImportGroups == R.JavaImportGroups &&
3458 JavaScriptQuotes == R.JavaScriptQuotes &&
3459 JavaScriptWrapImports == R.JavaScriptWrapImports &&
3460 KeepEmptyLinesAtTheStartOfBlocks ==
3461 R.KeepEmptyLinesAtTheStartOfBlocks &&
3462 LambdaBodyIndentation == R.LambdaBodyIndentation &&
3463 MacroBlockBegin == R.MacroBlockBegin &&
3464 MacroBlockEnd == R.MacroBlockEnd &&
3465 MaxEmptyLinesToKeep == R.MaxEmptyLinesToKeep &&
3466 NamespaceIndentation == R.NamespaceIndentation &&
3467 NamespaceMacros == R.NamespaceMacros &&
3468 ObjCBinPackProtocolList == R.ObjCBinPackProtocolList &&
3469 ObjCBlockIndentWidth == R.ObjCBlockIndentWidth &&
3470 ObjCBreakBeforeNestedBlockParam ==
3471 R.ObjCBreakBeforeNestedBlockParam &&
3472 ObjCSpaceAfterProperty == R.ObjCSpaceAfterProperty &&
3473 ObjCSpaceBeforeProtocolList == R.ObjCSpaceBeforeProtocolList &&
3474 PenaltyBreakAssignment == R.PenaltyBreakAssignment &&
3475 PenaltyBreakBeforeFirstCallParameter ==
3476 R.PenaltyBreakBeforeFirstCallParameter &&
3477 PenaltyBreakComment == R.PenaltyBreakComment &&
3478 PenaltyBreakFirstLessLess == R.PenaltyBreakFirstLessLess &&
3479 PenaltyBreakString == R.PenaltyBreakString &&
3480 PenaltyExcessCharacter == R.PenaltyExcessCharacter &&
3481 PenaltyReturnTypeOnItsOwnLine == R.PenaltyReturnTypeOnItsOwnLine &&
3482 PenaltyBreakTemplateDeclaration ==
3483 R.PenaltyBreakTemplateDeclaration &&
3484 PointerAlignment == R.PointerAlignment &&
3485 RawStringFormats == R.RawStringFormats &&
3486 ReferenceAlignment == R.ReferenceAlignment &&
3487 ShortNamespaceLines == R.ShortNamespaceLines &&
3488 SortIncludes == R.SortIncludes &&
3489 SortJavaStaticImport == R.SortJavaStaticImport &&
3490 SpaceAfterCStyleCast == R.SpaceAfterCStyleCast &&
3491 SpaceAfterLogicalNot == R.SpaceAfterLogicalNot &&
3492 SpaceAfterTemplateKeyword == R.SpaceAfterTemplateKeyword &&
3493 SpaceBeforeAssignmentOperators == R.SpaceBeforeAssignmentOperators &&
3494 SpaceBeforeCaseColon == R.SpaceBeforeCaseColon &&
3495 SpaceBeforeCpp11BracedList == R.SpaceBeforeCpp11BracedList &&
3496 SpaceBeforeCtorInitializerColon ==
3497 R.SpaceBeforeCtorInitializerColon &&
3498 SpaceBeforeInheritanceColon == R.SpaceBeforeInheritanceColon &&
3499 SpaceBeforeParens == R.SpaceBeforeParens &&
3500 SpaceAroundPointerQualifiers == R.SpaceAroundPointerQualifiers &&
3501 SpaceBeforeRangeBasedForLoopColon ==
3502 R.SpaceBeforeRangeBasedForLoopColon &&
3503 SpaceInEmptyBlock == R.SpaceInEmptyBlock &&
3504 SpaceInEmptyParentheses == R.SpaceInEmptyParentheses &&
3505 SpacesBeforeTrailingComments == R.SpacesBeforeTrailingComments &&
3506 SpacesInAngles == R.SpacesInAngles &&
3507 SpacesInConditionalStatement == R.SpacesInConditionalStatement &&
3508 SpacesInContainerLiterals == R.SpacesInContainerLiterals &&
3509 SpacesInCStyleCastParentheses == R.SpacesInCStyleCastParentheses &&
3510 SpacesInLineCommentPrefix.Minimum ==
3511 R.SpacesInLineCommentPrefix.Minimum &&
3512 SpacesInLineCommentPrefix.Maximum ==
3513 R.SpacesInLineCommentPrefix.Maximum &&
3514 SpacesInParentheses == R.SpacesInParentheses &&
3515 SpacesInSquareBrackets == R.SpacesInSquareBrackets &&
3516 SpaceBeforeSquareBrackets == R.SpaceBeforeSquareBrackets &&
3517 BitFieldColonSpacing == R.BitFieldColonSpacing &&
3518 Standard == R.Standard &&
3519 StatementAttributeLikeMacros == R.StatementAttributeLikeMacros &&
3520 StatementMacros == R.StatementMacros && TabWidth == R.TabWidth &&
3521 UseTab == R.UseTab && UseCRLF == R.UseCRLF &&
3522 TypenameMacros == R.TypenameMacros;
3523 }
3524
3525 llvm::Optional<FormatStyle> GetLanguageStyle(LanguageKind Language) const;
3526
3527 // Stores per-language styles. A FormatStyle instance inside has an empty
3528 // StyleSet. A FormatStyle instance returned by the Get method has its
3529 // StyleSet set to a copy of the originating StyleSet, effectively keeping the
3530 // internal representation of that StyleSet alive.
3531 //
3532 // The memory management and ownership reminds of a birds nest: chicks
3533 // leaving the nest take photos of the nest with them.
3534 struct FormatStyleSet {
3535 typedef std::map<FormatStyle::LanguageKind, FormatStyle> MapType;
3536
3537 llvm::Optional<FormatStyle> Get(FormatStyle::LanguageKind Language) const;
3538
3539 // Adds \p Style to this FormatStyleSet. Style must not have an associated
3540 // FormatStyleSet.
3541 // Style.Language should be different than LK_None. If this FormatStyleSet
3542 // already contains an entry for Style.Language, that gets replaced with the
3543 // passed Style.
3544 void Add(FormatStyle Style);
3545
3546 // Clears this FormatStyleSet.
3547 void Clear();
3548
3549 private:
3550 std::shared_ptr<MapType> Styles;
3551 };
3552
3553 static FormatStyleSet BuildStyleSetFromConfiguration(
3554 const FormatStyle &MainStyle,
3555 const std::vector<FormatStyle> &ConfigurationStyles);
3556
3557 private:
3558 FormatStyleSet StyleSet;
3559
3560 friend std::error_code
3561 parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style,
3562 bool AllowUnknownOptions,
3563 llvm::SourceMgr::DiagHandlerTy DiagHandler,
3564 void *DiagHandlerCtxt);
3565 };
3566
3567 /// Returns a format style complying with the LLVM coding standards:
3568 /// http://llvm.org/docs/CodingStandards.html.
3569 FormatStyle getLLVMStyle(
3570 FormatStyle::LanguageKind Language = FormatStyle::LanguageKind::LK_Cpp);
3571
3572 /// Returns a format style complying with one of Google's style guides:
3573 /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
3574 /// http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml.
3575 /// https://developers.google.com/protocol-buffers/docs/style.
3576 FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language);
3577
3578 /// Returns a format style complying with Chromium's style guide:
3579 /// http://www.chromium.org/developers/coding-style.
3580 FormatStyle getChromiumStyle(FormatStyle::LanguageKind Language);
3581
3582 /// Returns a format style complying with Mozilla's style guide:
3583 /// https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style.
3584 FormatStyle getMozillaStyle();
3585
3586 /// Returns a format style complying with Webkit's style guide:
3587 /// http://www.webkit.org/coding/coding-style.html
3588 FormatStyle getWebKitStyle();
3589
3590 /// Returns a format style complying with GNU Coding Standards:
3591 /// http://www.gnu.org/prep/standards/standards.html
3592 FormatStyle getGNUStyle();
3593
3594 /// Returns a format style complying with Microsoft style guide:
3595 /// https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017
3596 FormatStyle getMicrosoftStyle(FormatStyle::LanguageKind Language);
3597
3598 /// Returns style indicating formatting should be not applied at all.
3599 FormatStyle getNoStyle();
3600
3601 /// Gets a predefined style for the specified language by name.
3602 ///
3603 /// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
3604 /// compared case-insensitively.
3605 ///
3606 /// Returns ``true`` if the Style has been set.
3607 bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language,
3608 FormatStyle *Style);
3609
3610 /// Parse configuration from YAML-formatted text.
3611 ///
3612 /// Style->Language is used to get the base style, if the ``BasedOnStyle``
3613 /// option is present.
3614 ///
3615 /// The FormatStyleSet of Style is reset.
3616 ///
3617 /// When ``BasedOnStyle`` is not present, options not present in the YAML
3618 /// document, are retained in \p Style.
3619 ///
3620 /// If AllowUnknownOptions is true, no errors are emitted if unknown
3621 /// format options are occured.
3622 ///
3623 /// If set all diagnostics are emitted through the DiagHandler.
3624 std::error_code
3625 parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style,
3626 bool AllowUnknownOptions = false,
3627 llvm::SourceMgr::DiagHandlerTy DiagHandler = nullptr,
3628 void *DiagHandlerCtx = nullptr);
3629
3630 /// Like above but accepts an unnamed buffer.
3631 inline std::error_code parseConfiguration(StringRef Config, FormatStyle *Style,
3632 bool AllowUnknownOptions = false) {
3633 return parseConfiguration(llvm::MemoryBufferRef(Config, "YAML"), Style,
3634 AllowUnknownOptions);
3635 }
3636
3637 /// Gets configuration in a YAML string.
3638 std::string configurationAsText(const FormatStyle &Style);
3639
3640 /// Returns the replacements necessary to sort all ``#include`` blocks
3641 /// that are affected by ``Ranges``.
3642 tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
3643 ArrayRef<tooling::Range> Ranges,
3644 StringRef FileName,
3645 unsigned *Cursor = nullptr);
3646
3647 /// Returns the replacements corresponding to applying and formatting
3648 /// \p Replaces on success; otheriwse, return an llvm::Error carrying
3649 /// llvm::StringError.
3650 llvm::Expected<tooling::Replacements>
3651 formatReplacements(StringRef Code, const tooling::Replacements &Replaces,
3652 const FormatStyle &Style);
3653
3654 /// Returns the replacements corresponding to applying \p Replaces and
3655 /// cleaning up the code after that on success; otherwise, return an llvm::Error
3656 /// carrying llvm::StringError.
3657 /// This also supports inserting/deleting C++ #include directives:
3658 /// - If a replacement has offset UINT_MAX, length 0, and a replacement text
3659 /// that is an #include directive, this will insert the #include into the
3660 /// correct block in the \p Code.
3661 /// - If a replacement has offset UINT_MAX, length 1, and a replacement text
3662 /// that is the name of the header to be removed, the header will be removed
3663 /// from \p Code if it exists.
3664 /// The include manipulation is done via `tooling::HeaderInclude`, see its
3665 /// documentation for more details on how include insertion points are found and
3666 /// what edits are produced.
3667 llvm::Expected<tooling::Replacements>
3668 cleanupAroundReplacements(StringRef Code, const tooling::Replacements &Replaces,
3669 const FormatStyle &Style);
3670
3671 /// Represents the status of a formatting attempt.
3672 struct FormattingAttemptStatus {
3673 /// A value of ``false`` means that any of the affected ranges were not
3674 /// formatted due to a non-recoverable syntax error.
3675 bool FormatComplete = true;
3676
3677 /// If ``FormatComplete`` is false, ``Line`` records a one-based
3678 /// original line number at which a syntax error might have occurred. This is
3679 /// based on a best-effort analysis and could be imprecise.
3680 unsigned Line = 0;
3681 };
3682
3683 /// Reformats the given \p Ranges in \p Code.
3684 ///
3685 /// Each range is extended on either end to its next bigger logic unit, i.e.
3686 /// everything that might influence its formatting or might be influenced by its
3687 /// formatting.
3688 ///
3689 /// Returns the ``Replacements`` necessary to make all \p Ranges comply with
3690 /// \p Style.
3691 ///
3692 /// If ``Status`` is non-null, its value will be populated with the status of
3693 /// this formatting attempt. See \c FormattingAttemptStatus.
3694 tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
3695 ArrayRef<tooling::Range> Ranges,
3696 StringRef FileName = "<stdin>",
3697 FormattingAttemptStatus *Status = nullptr);
3698
3699 /// Same as above, except if ``IncompleteFormat`` is non-null, its value
3700 /// will be set to true if any of the affected ranges were not formatted due to
3701 /// a non-recoverable syntax error.
3702 tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
3703 ArrayRef<tooling::Range> Ranges,
3704 StringRef FileName, bool *IncompleteFormat);
3705
3706 /// Clean up any erroneous/redundant code in the given \p Ranges in \p
3707 /// Code.
3708 ///
3709 /// Returns the ``Replacements`` that clean up all \p Ranges in \p Code.
3710 tooling::Replacements cleanup(const FormatStyle &Style, StringRef Code,
3711 ArrayRef<tooling::Range> Ranges,
3712 StringRef FileName = "<stdin>");
3713
3714 /// Fix namespace end comments in the given \p Ranges in \p Code.
3715 ///
3716 /// Returns the ``Replacements`` that fix the namespace comments in all
3717 /// \p Ranges in \p Code.
3718 tooling::Replacements fixNamespaceEndComments(const FormatStyle &Style,
3719 StringRef Code,
3720 ArrayRef<tooling::Range> Ranges,
3721 StringRef FileName = "<stdin>");
3722
3723 /// Sort consecutive using declarations in the given \p Ranges in
3724 /// \p Code.
3725 ///
3726 /// Returns the ``Replacements`` that sort the using declarations in all
3727 /// \p Ranges in \p Code.
3728 tooling::Replacements sortUsingDeclarations(const FormatStyle &Style,
3729 StringRef Code,
3730 ArrayRef<tooling::Range> Ranges,
3731 StringRef FileName = "<stdin>");
3732
3733 /// Returns the ``LangOpts`` that the formatter expects you to set.
3734 ///
3735 /// \param Style determines specific settings for lexing mode.
3736 LangOptions getFormattingLangOpts(const FormatStyle &Style = getLLVMStyle());
3737
3738 /// Description to be used for help text for a ``llvm::cl`` option for
3739 /// specifying format style. The description is closely related to the operation
3740 /// of ``getStyle()``.
3741 extern const char *StyleOptionHelpDescription;
3742
3743 /// The suggested format style to use by default. This allows tools using
3744 /// `getStyle` to have a consistent default style.
3745 /// Different builds can modify the value to the preferred styles.
3746 extern const char *DefaultFormatStyle;
3747
3748 /// The suggested predefined style to use as the fallback style in `getStyle`.
3749 /// Different builds can modify the value to the preferred styles.
3750 extern const char *DefaultFallbackStyle;
3751
3752 /// Construct a FormatStyle based on ``StyleName``.
3753 ///
3754 /// ``StyleName`` can take several forms:
3755 /// * "{<key>: <value>, ...}" - Set specic style parameters.
3756 /// * "<style name>" - One of the style names supported by
3757 /// getPredefinedStyle().
3758 /// * "file" - Load style configuration from a file called ``.clang-format``
3759 /// located in one of the parent directories of ``FileName`` or the current
3760 /// directory if ``FileName`` is empty.
3761 ///
3762 /// \param[in] StyleName Style name to interpret according to the description
3763 /// above.
3764 /// \param[in] FileName Path to start search for .clang-format if ``StyleName``
3765 /// == "file".
3766 /// \param[in] FallbackStyle The name of a predefined style used to fallback to
3767 /// in case \p StyleName is "file" and no file can be found.
3768 /// \param[in] Code The actual code to be formatted. Used to determine the
3769 /// language if the filename isn't sufficient.
3770 /// \param[in] FS The underlying file system, in which the file resides. By
3771 /// default, the file system is the real file system.
3772 /// \param[in] AllowUnknownOptions If true, unknown format options only
3773 /// emit a warning. If false, errors are emitted on unknown format
3774 /// options.
3775 ///
3776 /// \returns FormatStyle as specified by ``StyleName``. If ``StyleName`` is
3777 /// "file" and no file is found, returns ``FallbackStyle``. If no style could be
3778 /// determined, returns an Error.
3779 llvm::Expected<FormatStyle> getStyle(StringRef StyleName, StringRef FileName,
3780 StringRef FallbackStyle,
3781 StringRef Code = "",
3782 llvm::vfs::FileSystem *FS = nullptr,
3783 bool AllowUnknownOptions = false);
3784
3785 // Guesses the language from the ``FileName`` and ``Code`` to be formatted.
3786 // Defaults to FormatStyle::LK_Cpp.
3787 FormatStyle::LanguageKind guessLanguage(StringRef FileName, StringRef Code);
3788
3789 // Returns a string representation of ``Language``.
getLanguageName(FormatStyle::LanguageKind Language)3790 inline StringRef getLanguageName(FormatStyle::LanguageKind Language) {
3791 switch (Language) {
3792 case FormatStyle::LK_Cpp:
3793 return "C++";
3794 case FormatStyle::LK_CSharp:
3795 return "CSharp";
3796 case FormatStyle::LK_ObjC:
3797 return "Objective-C";
3798 case FormatStyle::LK_Java:
3799 return "Java";
3800 case FormatStyle::LK_JavaScript:
3801 return "JavaScript";
3802 case FormatStyle::LK_Json:
3803 return "Json";
3804 case FormatStyle::LK_Proto:
3805 return "Proto";
3806 case FormatStyle::LK_TableGen:
3807 return "TableGen";
3808 case FormatStyle::LK_TextProto:
3809 return "TextProto";
3810 default:
3811 return "Unknown";
3812 }
3813 }
3814
3815 } // end namespace format
3816 } // end namespace clang
3817
3818 namespace std {
3819 template <>
3820 struct is_error_code_enum<clang::format::ParseError> : std::true_type {};
3821 } // namespace std
3822
3823 #endif // LLVM_CLANG_FORMAT_FORMAT_H
3824