clang 18.0.0git
Format.h
Go to the documentation of this file.
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
20#include "llvm/ADT/ArrayRef.h"
21#include "llvm/Support/Regex.h"
22#include "llvm/Support/SourceMgr.h"
23#include <optional>
24#include <system_error>
25
26namespace llvm {
27namespace vfs {
28class FileSystem;
29}
30} // namespace llvm
31
32namespace clang {
33namespace format {
34
35enum class ParseError {
36 Success = 0,
37 Error,
44};
45class ParseErrorCategory final : public std::error_category {
46public:
47 const char *name() const noexcept override;
48 std::string message(int EV) const override;
49};
50const std::error_category &getParseCategory();
51std::error_code make_error_code(ParseError e);
52
53/// The ``FormatStyle`` is used to configure the formatting to follow
54/// specific guidelines.
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 ///.
60
61 /// The extra indent or outdent of access modifiers, e.g. ``public:``.
62 /// \version 3.3
64
65 /// Different styles for aligning after open brackets.
66 enum BracketAlignmentStyle : int8_t {
67 /// Align parameters on the open bracket, e.g.:
68 /// \code
69 /// someLongFunction(argument1,
70 /// argument2);
71 /// \endcode
73 /// Don't align, instead use ``ContinuationIndentWidth``, e.g.:
74 /// \code
75 /// someLongFunction(argument1,
76 /// argument2);
77 /// \endcode
79 /// Always break after an open bracket, if the parameters don't fit
80 /// on a single line, e.g.:
81 /// \code
82 /// someLongFunction(
83 /// argument1, argument2);
84 /// \endcode
86 /// Always break after an open bracket, if the parameters don't fit
87 /// on a single line. Closing brackets will be placed on a new line.
88 /// E.g.:
89 /// \code
90 /// someLongFunction(
91 /// argument1, argument2
92 /// )
93 /// \endcode
94 ///
95 /// \note
96 /// This currently only applies to braced initializer lists (when
97 /// ``Cpp11BracedListStyle`` is ``true``) and parentheses.
98 /// \endnote
100 };
101
102 /// If ``true``, horizontally aligns arguments after an open bracket.
103 ///
104 /// This applies to round brackets (parentheses), angle brackets and square
105 /// brackets.
106 /// \version 3.8
108
109 /// Different style for aligning array initializers.
111 /// Align array column and left justify the columns e.g.:
112 /// \code
113 /// struct test demo[] =
114 /// {
115 /// {56, 23, "hello"},
116 /// {-1, 93463, "world"},
117 /// {7, 5, "!!" }
118 /// };
119 /// \endcode
121 /// Align array column and right justify the columns e.g.:
122 /// \code
123 /// struct test demo[] =
124 /// {
125 /// {56, 23, "hello"},
126 /// {-1, 93463, "world"},
127 /// { 7, 5, "!!"}
128 /// };
129 /// \endcode
131 /// Don't align array initializer columns.
133 };
134 /// if not ``None``, when using initialization for an array of structs
135 /// aligns the fields into columns.
136 ///
137 /// \note
138 /// As of clang-format 15 this option only applied to arrays with equal
139 /// number of columns per row.
140 /// \endnote
141 ///
142 /// \version 13
144
145 /// Alignment options.
146 ///
147 /// They can also be read as a whole for compatibility. The choices are:
148 /// - None
149 /// - Consecutive
150 /// - AcrossEmptyLines
151 /// - AcrossComments
152 /// - AcrossEmptyLinesAndComments
153 ///
154 /// For example, to align across empty lines and not across comments, either
155 /// of these work.
156 /// \code
157 /// AlignConsecutiveMacros: AcrossEmptyLines
158 ///
159 /// AlignConsecutiveMacros:
160 /// Enabled: true
161 /// AcrossEmptyLines: true
162 /// AcrossComments: false
163 /// \endcode
165 /// Whether aligning is enabled.
166 /// \code
167 /// #define SHORT_NAME 42
168 /// #define LONGER_NAME 0x007f
169 /// #define EVEN_LONGER_NAME (2)
170 /// #define foo(x) (x * x)
171 /// #define bar(y, z) (y + z)
172 ///
173 /// int a = 1;
174 /// int somelongname = 2;
175 /// double c = 3;
176 ///
177 /// int aaaa : 1;
178 /// int b : 12;
179 /// int ccc : 8;
180 ///
181 /// int aaaa = 12;
182 /// float b = 23;
183 /// std::string ccc;
184 /// \endcode
186 /// Whether to align across empty lines.
187 /// \code
188 /// true:
189 /// int a = 1;
190 /// int somelongname = 2;
191 /// double c = 3;
192 ///
193 /// int d = 3;
194 ///
195 /// false:
196 /// int a = 1;
197 /// int somelongname = 2;
198 /// double c = 3;
199 ///
200 /// int d = 3;
201 /// \endcode
203 /// Whether to align across comments.
204 /// \code
205 /// true:
206 /// int d = 3;
207 /// /* A comment. */
208 /// double e = 4;
209 ///
210 /// false:
211 /// int d = 3;
212 /// /* A comment. */
213 /// double e = 4;
214 /// \endcode
216 /// Only for ``AlignConsecutiveAssignments``. Whether compound assignments
217 /// like ``+=`` are aligned along with ``=``.
218 /// \code
219 /// true:
220 /// a &= 2;
221 /// bbb = 2;
222 ///
223 /// false:
224 /// a &= 2;
225 /// bbb = 2;
226 /// \endcode
228 /// Only for ``AlignConsecutiveAssignments``. Whether short assignment
229 /// operators are left-padded to the same length as long ones in order to
230 /// put all assignment operators to the right of the left hand side.
231 /// \code
232 /// true:
233 /// a >>= 2;
234 /// bbb = 2;
235 ///
236 /// a = 2;
237 /// bbb >>= 2;
238 ///
239 /// false:
240 /// a >>= 2;
241 /// bbb = 2;
242 ///
243 /// a = 2;
244 /// bbb >>= 2;
245 /// \endcode
247 bool operator==(const AlignConsecutiveStyle &R) const {
248 return Enabled == R.Enabled && AcrossEmptyLines == R.AcrossEmptyLines &&
251 }
252 bool operator!=(const AlignConsecutiveStyle &R) const {
253 return !(*this == R);
254 }
255 };
256
257 /// Style of aligning consecutive macro definitions.
258 ///
259 /// ``Consecutive`` will result in formattings like:
260 /// \code
261 /// #define SHORT_NAME 42
262 /// #define LONGER_NAME 0x007f
263 /// #define EVEN_LONGER_NAME (2)
264 /// #define foo(x) (x * x)
265 /// #define bar(y, z) (y + z)
266 /// \endcode
267 /// \version 9
269 /// Style of aligning consecutive assignments.
270 ///
271 /// ``Consecutive`` will result in formattings like:
272 /// \code
273 /// int a = 1;
274 /// int somelongname = 2;
275 /// double c = 3;
276 /// \endcode
277 /// \version 3.8
279 /// Style of aligning consecutive bit fields.
280 ///
281 /// ``Consecutive`` will align the bitfield separators of consecutive lines.
282 /// This will result in formattings like:
283 /// \code
284 /// int aaaa : 1;
285 /// int b : 12;
286 /// int ccc : 8;
287 /// \endcode
288 /// \version 11
290 /// Style of aligning consecutive declarations.
291 ///
292 /// ``Consecutive`` will align the declaration names of consecutive lines.
293 /// This will result in formattings like:
294 /// \code
295 /// int aaaa = 12;
296 /// float b = 23;
297 /// std::string ccc;
298 /// \endcode
299 /// \version 3.8
301
302 /// Alignment options.
303 ///
305 /// Whether aligning is enabled.
306 /// \code
307 /// true:
308 /// switch (level) {
309 /// case log::info: return "info:";
310 /// case log::warning: return "warning:";
311 /// default: return "";
312 /// }
313 ///
314 /// false:
315 /// switch (level) {
316 /// case log::info: return "info:";
317 /// case log::warning: return "warning:";
318 /// default: return "";
319 /// }
320 /// \endcode
322 /// Whether to align across empty lines.
323 /// \code
324 /// true:
325 /// switch (level) {
326 /// case log::info: return "info:";
327 /// case log::warning: return "warning:";
328 ///
329 /// default: return "";
330 /// }
331 ///
332 /// false:
333 /// switch (level) {
334 /// case log::info: return "info:";
335 /// case log::warning: return "warning:";
336 ///
337 /// default: return "";
338 /// }
339 /// \endcode
341 /// Whether to align across comments.
342 /// \code
343 /// true:
344 /// switch (level) {
345 /// case log::info: return "info:";
346 /// case log::warning: return "warning:";
347 /// /* A comment. */
348 /// default: return "";
349 /// }
350 ///
351 /// false:
352 /// switch (level) {
353 /// case log::info: return "info:";
354 /// case log::warning: return "warning:";
355 /// /* A comment. */
356 /// default: return "";
357 /// }
358 /// \endcode
360 /// Whether aligned case labels are aligned on the colon, or on the
361 /// , or on the tokens after the colon.
362 /// \code
363 /// true:
364 /// switch (level) {
365 /// case log::info : return "info:";
366 /// case log::warning: return "warning:";
367 /// default : return "";
368 /// }
369 ///
370 /// false:
371 /// switch (level) {
372 /// case log::info: return "info:";
373 /// case log::warning: return "warning:";
374 /// default: return "";
375 /// }
376 /// \endcode
379 return Enabled == R.Enabled && AcrossEmptyLines == R.AcrossEmptyLines &&
382 }
383 };
384
385 /// Style of aligning consecutive short case labels.
386 /// Only applies if ``AllowShortCaseLabelsOnASingleLine`` is ``true``.
387 ///
388 /// \code{.yaml}
389 /// # Example of usage:
390 /// AlignConsecutiveShortCaseStatements:
391 /// Enabled: true
392 /// AcrossEmptyLines: true
393 /// AcrossComments: true
394 /// AlignCaseColons: false
395 /// \endcode
396 /// \version 17
398
399 /// Different styles for aligning escaped newlines.
401 /// Don't align escaped newlines.
402 /// \code
403 /// #define A \
404 /// int aaaa; \
405 /// int b; \
406 /// int dddddddddd;
407 /// \endcode
409 /// Align escaped newlines as far left as possible.
410 /// \code
411 /// true:
412 /// #define A \
413 /// int aaaa; \
414 /// int b; \
415 /// int dddddddddd;
416 ///
417 /// false:
418 /// \endcode
420 /// Align escaped newlines in the right-most column.
421 /// \code
422 /// #define A \
423 /// int aaaa; \
424 /// int b; \
425 /// int dddddddddd;
426 /// \endcode
428 };
429
430 /// Options for aligning backslashes in escaped newlines.
431 /// \version 5
433
434 /// Different styles for aligning operands.
435 enum OperandAlignmentStyle : int8_t {
436 /// Do not align operands of binary and ternary expressions.
437 /// The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
438 /// the start of the line.
440 /// Horizontally align operands of binary and ternary expressions.
441 ///
442 /// Specifically, this aligns operands of a single expression that needs
443 /// to be split over multiple lines, e.g.:
444 /// \code
445 /// int aaa = bbbbbbbbbbbbbbb +
446 /// ccccccccccccccc;
447 /// \endcode
448 ///
449 /// When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
450 /// aligned with the operand on the first line.
451 /// \code
452 /// int aaa = bbbbbbbbbbbbbbb
453 /// + ccccccccccccccc;
454 /// \endcode
456 /// Horizontally align operands of binary and ternary expressions.
457 ///
458 /// This is similar to ``AO_Align``, except when
459 /// ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
460 /// that the wrapped operand is aligned with the operand on the first line.
461 /// \code
462 /// int aaa = bbbbbbbbbbbbbbb
463 /// + ccccccccccccccc;
464 /// \endcode
466 };
467
468 /// If ``true``, horizontally align operands of binary and ternary
469 /// expressions.
470 /// \version 3.5
472
473 /// Enums for AlignTrailingComments
475 /// Leave trailing comments as they are.
476 /// \code
477 /// int a; // comment
478 /// int ab; // comment
479 ///
480 /// int abc; // comment
481 /// int abcd; // comment
482 /// \endcode
484 /// Align trailing comments.
485 /// \code
486 /// int a; // comment
487 /// int ab; // comment
488 ///
489 /// int abc; // comment
490 /// int abcd; // comment
491 /// \endcode
493 /// Don't align trailing comments but other formatter applies.
494 /// \code
495 /// int a; // comment
496 /// int ab; // comment
497 ///
498 /// int abc; // comment
499 /// int abcd; // comment
500 /// \endcode
502 };
503
504 /// Alignment options
506 /// Specifies the way to align trailing comments.
508 /// How many empty lines to apply alignment.
509 /// When both ``MaxEmptyLinesToKeep`` and ``OverEmptyLines`` are set to 2,
510 /// it formats like below.
511 /// \code
512 /// int a; // all these
513 ///
514 /// int ab; // comments are
515 ///
516 ///
517 /// int abcdef; // aligned
518 /// \endcode
519 ///
520 /// When ``MaxEmptyLinesToKeep`` is set to 2 and ``OverEmptyLines`` is set
521 /// to 1, it formats like below.
522 /// \code
523 /// int a; // these are
524 ///
525 /// int ab; // aligned
526 ///
527 ///
528 /// int abcdef; // but this isn't
529 /// \endcode
531
533 return Kind == R.Kind && OverEmptyLines == R.OverEmptyLines;
534 }
536 return !(*this == R);
537 }
538 };
539
540 /// Control of trailing comments.
541 ///
542 /// The alignment stops at closing braces after a line break, and only
543 /// followed by other closing braces, a (``do-``) ``while``, a lambda call, or
544 /// a semicolon.
545 ///
546 /// \note
547 /// As of clang-format 16 this option is not a bool but can be set
548 /// to the options. Conventional bool options still can be parsed as before.
549 /// \endnote
550 ///
551 /// \code{.yaml}
552 /// # Example of usage:
553 /// AlignTrailingComments:
554 /// Kind: Always
555 /// OverEmptyLines: 2
556 /// \endcode
557 /// \version 3.7
559
560 /// \brief If a function call or braced initializer list doesn't fit on a
561 /// line, allow putting all arguments onto the next line, even if
562 /// ``BinPackArguments`` is ``false``.
563 /// \code
564 /// true:
565 /// callFunction(
566 /// a, b, c, d);
567 ///
568 /// false:
569 /// callFunction(a,
570 /// b,
571 /// c,
572 /// d);
573 /// \endcode
574 /// \version 9
576
577 /// This option is **deprecated**. See ``NextLine`` of
578 /// ``PackConstructorInitializers``.
579 /// \version 9
580 // bool AllowAllConstructorInitializersOnNextLine;
581
582 /// If the function declaration doesn't fit on a line,
583 /// allow putting all parameters of a function declaration onto
584 /// the next line even if ``BinPackParameters`` is ``false``.
585 /// \code
586 /// true:
587 /// void myFunction(
588 /// int a, int b, int c, int d, int e);
589 ///
590 /// false:
591 /// void myFunction(int a,
592 /// int b,
593 /// int c,
594 /// int d,
595 /// int e);
596 /// \endcode
597 /// \version 3.3
599
600 /// Different ways to break before a noexcept specifier.
602 /// No line break allowed.
603 /// \code
604 /// void foo(int arg1,
605 /// double arg2) noexcept;
606 ///
607 /// void bar(int arg1, double arg2) noexcept(
608 /// noexcept(baz(arg1)) &&
609 /// noexcept(baz(arg2)));
610 /// \endcode
612 /// For a simple ``noexcept`` there is no line break allowed, but when we
613 /// have a condition it is.
614 /// \code
615 /// void foo(int arg1,
616 /// double arg2) noexcept;
617 ///
618 /// void bar(int arg1, double arg2)
619 /// noexcept(noexcept(baz(arg1)) &&
620 /// noexcept(baz(arg2)));
621 /// \endcode
623 /// Line breaks are allowed. But note that because of the associated
624 /// penalties ``clang-format`` often prefers not to break before the
625 /// ``noexcept``.
626 /// \code
627 /// void foo(int arg1,
628 /// double arg2) noexcept;
629 ///
630 /// void bar(int arg1, double arg2)
631 /// noexcept(noexcept(baz(arg1)) &&
632 /// noexcept(baz(arg2)));
633 /// \endcode
635 };
636
637 /// Controls if there could be a line break before a ``noexcept`` specifier.
638 /// \version 18
640
641 /// Different styles for merging short blocks containing at most one
642 /// statement.
643 enum ShortBlockStyle : int8_t {
644 /// Never merge blocks into a single line.
645 /// \code
646 /// while (true) {
647 /// }
648 /// while (true) {
649 /// continue;
650 /// }
651 /// \endcode
653 /// Only merge empty blocks.
654 /// \code
655 /// while (true) {}
656 /// while (true) {
657 /// continue;
658 /// }
659 /// \endcode
661 /// Always merge short blocks into a single line.
662 /// \code
663 /// while (true) {}
664 /// while (true) { continue; }
665 /// \endcode
667 };
668
669 /// Dependent on the value, ``while (true) { continue; }`` can be put on a
670 /// single line.
671 /// \version 3.5
673
674 /// If ``true``, short case labels will be contracted to a single line.
675 /// \code
676 /// true: false:
677 /// switch (a) { vs. switch (a) {
678 /// case 1: x = 1; break; case 1:
679 /// case 2: return; x = 1;
680 /// } break;
681 /// case 2:
682 /// return;
683 /// }
684 /// \endcode
685 /// \version 3.6
687
688 /// Allow short compound requirement on a single line.
689 /// \code
690 /// true:
691 /// template <typename T>
692 /// concept c = requires(T x) {
693 /// { x + 1 } -> std::same_as<int>;
694 /// };
695 ///
696 /// false:
697 /// template <typename T>
698 /// concept c = requires(T x) {
699 /// {
700 /// x + 1
701 /// } -> std::same_as<int>;
702 /// };
703 /// \endcode
704 /// \version 18
706
707 /// Allow short enums on a single line.
708 /// \code
709 /// true:
710 /// enum { A, B } myEnum;
711 ///
712 /// false:
713 /// enum {
714 /// A,
715 /// B
716 /// } myEnum;
717 /// \endcode
718 /// \version 11
720
721 /// Different styles for merging short functions containing at most one
722 /// statement.
723 enum ShortFunctionStyle : int8_t {
724 /// Never merge functions into a single line.
726 /// Only merge functions defined inside a class. Same as "inline",
727 /// except it does not implies "empty": i.e. top level empty functions
728 /// are not merged either.
729 /// \code
730 /// class Foo {
731 /// void f() { foo(); }
732 /// };
733 /// void f() {
734 /// foo();
735 /// }
736 /// void f() {
737 /// }
738 /// \endcode
740 /// Only merge empty functions.
741 /// \code
742 /// void f() {}
743 /// void f2() {
744 /// bar2();
745 /// }
746 /// \endcode
748 /// Only merge functions defined inside a class. Implies "empty".
749 /// \code
750 /// class Foo {
751 /// void f() { foo(); }
752 /// };
753 /// void f() {
754 /// foo();
755 /// }
756 /// void f() {}
757 /// \endcode
759 /// Merge all functions fitting on a single line.
760 /// \code
761 /// class Foo {
762 /// void f() { foo(); }
763 /// };
764 /// void f() { bar(); }
765 /// \endcode
767 };
768
769 /// Dependent on the value, ``int f() { return 0; }`` can be put on a
770 /// single line.
771 /// \version 3.5
773
774 /// Different styles for handling short if statements.
775 enum ShortIfStyle : int8_t {
776 /// Never put short ifs on the same line.
777 /// \code
778 /// if (a)
779 /// return;
780 ///
781 /// if (b)
782 /// return;
783 /// else
784 /// return;
785 ///
786 /// if (c)
787 /// return;
788 /// else {
789 /// return;
790 /// }
791 /// \endcode
793 /// Put short ifs on the same line only if there is no else statement.
794 /// \code
795 /// if (a) return;
796 ///
797 /// if (b)
798 /// return;
799 /// else
800 /// return;
801 ///
802 /// if (c)
803 /// return;
804 /// else {
805 /// return;
806 /// }
807 /// \endcode
809 /// Put short ifs, but not else ifs nor else statements, on the same line.
810 /// \code
811 /// if (a) return;
812 ///
813 /// if (b) return;
814 /// else if (b)
815 /// return;
816 /// else
817 /// return;
818 ///
819 /// if (c) return;
820 /// else {
821 /// return;
822 /// }
823 /// \endcode
825 /// Always put short ifs, else ifs and else statements on the same
826 /// line.
827 /// \code
828 /// if (a) return;
829 ///
830 /// if (b) return;
831 /// else return;
832 ///
833 /// if (c) return;
834 /// else {
835 /// return;
836 /// }
837 /// \endcode
839 };
840
841 /// Dependent on the value, ``if (a) return;`` can be put on a single line.
842 /// \version 3.3
844
845 /// Different styles for merging short lambdas containing at most one
846 /// statement.
847 enum ShortLambdaStyle : int8_t {
848 /// Never merge lambdas into a single line.
850 /// Only merge empty lambdas.
851 /// \code
852 /// auto lambda = [](int a) {};
853 /// auto lambda2 = [](int a) {
854 /// return a;
855 /// };
856 /// \endcode
858 /// Merge lambda into a single line if the lambda is argument of a function.
859 /// \code
860 /// auto lambda = [](int x, int y) {
861 /// return x < y;
862 /// };
863 /// sort(a.begin(), a.end(), [](int x, int y) { return x < y; });
864 /// \endcode
866 /// Merge all lambdas fitting on a single line.
867 /// \code
868 /// auto lambda = [](int a) {};
869 /// auto lambda2 = [](int a) { return a; };
870 /// \endcode
872 };
873
874 /// Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
875 /// single line.
876 /// \version 9
878
879 /// If ``true``, ``while (true) continue;`` can be put on a single
880 /// line.
881 /// \version 3.7
883
884 /// Different ways to break after the function definition return type.
885 /// This option is **deprecated** and is retained for backwards compatibility.
887 /// Break after return type automatically.
888 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
890 /// Always break after the return type.
892 /// Always break after the return types of top-level functions.
894 };
895
896 /// Different ways to break after the function definition or
897 /// declaration return type.
899 /// Break after return type automatically.
900 /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
901 /// \code
902 /// class A {
903 /// int f() { return 0; };
904 /// };
905 /// int f();
906 /// int f() { return 1; }
907 /// \endcode
909 /// Always break after the return type.
910 /// \code
911 /// class A {
912 /// int
913 /// f() {
914 /// return 0;
915 /// };
916 /// };
917 /// int
918 /// f();
919 /// int
920 /// f() {
921 /// return 1;
922 /// }
923 /// \endcode
925 /// Always break after the return types of top-level functions.
926 /// \code
927 /// class A {
928 /// int f() { return 0; };
929 /// };
930 /// int
931 /// f();
932 /// int
933 /// f() {
934 /// return 1;
935 /// }
936 /// \endcode
938 /// Always break after the return type of function definitions.
939 /// \code
940 /// class A {
941 /// int
942 /// f() {
943 /// return 0;
944 /// };
945 /// };
946 /// int f();
947 /// int
948 /// f() {
949 /// return 1;
950 /// }
951 /// \endcode
953 /// Always break after the return type of top-level definitions.
954 /// \code
955 /// class A {
956 /// int f() { return 0; };
957 /// };
958 /// int f();
959 /// int
960 /// f() {
961 /// return 1;
962 /// }
963 /// \endcode
965 };
966
967 /// The function definition return type breaking style to use. This
968 /// option is **deprecated** and is retained for backwards compatibility.
969 /// \version 3.7
971
972 /// The function declaration return type breaking style to use.
973 /// \version 3.8
975
976 /// If ``true``, always break before multiline string literals.
977 ///
978 /// This flag is mean to make cases where there are multiple multiline strings
979 /// in a file look more consistent. Thus, it will only take effect if wrapping
980 /// the string at that point leads to it being indented
981 /// ``ContinuationIndentWidth`` spaces from the start of the line.
982 /// \code
983 /// true: false:
984 /// aaaa = vs. aaaa = "bbbb"
985 /// "bbbb" "cccc";
986 /// "cccc";
987 /// \endcode
988 /// \version 3.4
990
991 /// Different ways to break after the template declaration.
993 /// Do not force break before declaration.
994 /// ``PenaltyBreakTemplateDeclaration`` is taken into account.
995 /// \code
996 /// template <typename T> T foo() {
997 /// }
998 /// template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
999 /// int bbbbbbbbbbbbbbbbbbbbb) {
1000 /// }
1001 /// \endcode
1003 /// Force break after template declaration only when the following
1004 /// declaration spans multiple lines.
1005 /// \code
1006 /// template <typename T> T foo() {
1007 /// }
1008 /// template <typename T>
1009 /// T foo(int aaaaaaaaaaaaaaaaaaaaa,
1010 /// int bbbbbbbbbbbbbbbbbbbbb) {
1011 /// }
1012 /// \endcode
1014 /// Always break after template declaration.
1015 /// \code
1016 /// template <typename T>
1017 /// T foo() {
1018 /// }
1019 /// template <typename T>
1020 /// T foo(int aaaaaaaaaaaaaaaaaaaaa,
1021 /// int bbbbbbbbbbbbbbbbbbbbb) {
1022 /// }
1023 /// \endcode
1024 BTDS_Yes
1026
1027 /// The template declaration breaking style to use.
1028 /// \version 3.4
1030
1031 /// A vector of strings that should be interpreted as attributes/qualifiers
1032 /// instead of identifiers. This can be useful for language extensions or
1033 /// static analyzer annotations.
1034 ///
1035 /// For example:
1036 /// \code
1037 /// x = (char *__capability)&y;
1038 /// int function(void) __unused;
1039 /// void only_writes_to_buffer(char *__output buffer);
1040 /// \endcode
1041 ///
1042 /// In the .clang-format configuration file, this can be configured like:
1043 /// \code{.yaml}
1044 /// AttributeMacros: ['__capability', '__output', '__unused']
1045 /// \endcode
1046 ///
1047 /// \version 12
1048 std::vector<std::string> AttributeMacros;
1049
1050 /// If ``false``, a function call's arguments will either be all on the
1051 /// same line or will have one line each.
1052 /// \code
1053 /// true:
1054 /// void f() {
1055 /// f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
1056 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
1057 /// }
1058 ///
1059 /// false:
1060 /// void f() {
1061 /// f(aaaaaaaaaaaaaaaaaaaa,
1062 /// aaaaaaaaaaaaaaaaaaaa,
1063 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
1064 /// }
1065 /// \endcode
1066 /// \version 3.7
1068
1069 /// If ``false``, a function declaration's or function definition's
1070 /// parameters will either all be on the same line or will have one line each.
1071 /// \code
1072 /// true:
1073 /// void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
1074 /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
1075 ///
1076 /// false:
1077 /// void f(int aaaaaaaaaaaaaaaaaaaa,
1078 /// int aaaaaaaaaaaaaaaaaaaa,
1079 /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
1080 /// \endcode
1081 /// \version 3.7
1083
1084 /// Styles for adding spacing around ``:`` in bitfield definitions.
1086 /// Add one space on each side of the ``:``
1087 /// \code
1088 /// unsigned bf : 2;
1089 /// \endcode
1091 /// Add no space around the ``:`` (except when needed for
1092 /// ``AlignConsecutiveBitFields``).
1093 /// \code
1094 /// unsigned bf:2;
1095 /// \endcode
1097 /// Add space before the ``:`` only
1098 /// \code
1099 /// unsigned bf :2;
1100 /// \endcode
1102 /// Add space after the ``:`` only (space may be added before if
1103 /// needed for ``AlignConsecutiveBitFields``).
1104 /// \code
1105 /// unsigned bf: 2;
1106 /// \endcode
1109 /// The BitFieldColonSpacingStyle to use for bitfields.
1110 /// \version 12
1112
1113 /// The number of columns to use to indent the contents of braced init lists.
1114 /// If unset, ``ContinuationIndentWidth`` is used.
1115 /// \code
1116 /// AlignAfterOpenBracket: AlwaysBreak
1117 /// BracedInitializerIndentWidth: 2
1118 ///
1119 /// void f() {
1120 /// SomeClass c{
1121 /// "foo",
1122 /// "bar",
1123 /// "baz",
1124 /// };
1125 /// auto s = SomeStruct{
1126 /// .foo = "foo",
1127 /// .bar = "bar",
1128 /// .baz = "baz",
1129 /// };
1130 /// SomeArrayT a[3] = {
1131 /// {
1132 /// foo,
1133 /// bar,
1134 /// },
1135 /// {
1136 /// foo,
1137 /// bar,
1138 /// },
1139 /// SomeArrayT{},
1140 /// };
1141 /// }
1142 /// \endcode
1143 /// \version 17
1144 std::optional<unsigned> BracedInitializerIndentWidth;
1145
1146 /// Different ways to wrap braces after control statements.
1148 /// Never wrap braces after a control statement.
1149 /// \code
1150 /// if (foo()) {
1151 /// } else {
1152 /// }
1153 /// for (int i = 0; i < 10; ++i) {
1154 /// }
1155 /// \endcode
1157 /// Only wrap braces after a multi-line control statement.
1158 /// \code
1159 /// if (foo && bar &&
1160 /// baz)
1161 /// {
1162 /// quux();
1163 /// }
1164 /// while (foo || bar) {
1165 /// }
1166 /// \endcode
1168 /// Always wrap braces after a control statement.
1169 /// \code
1170 /// if (foo())
1171 /// {
1172 /// } else
1173 /// {}
1174 /// for (int i = 0; i < 10; ++i)
1175 /// {}
1176 /// \endcode
1179
1180 /// Precise control over the wrapping of braces.
1181 /// \code
1182 /// # Should be declared this way:
1183 /// BreakBeforeBraces: Custom
1184 /// BraceWrapping:
1185 /// AfterClass: true
1186 /// \endcode
1188 /// Wrap case labels.
1189 /// \code
1190 /// false: true:
1191 /// switch (foo) { vs. switch (foo) {
1192 /// case 1: { case 1:
1193 /// bar(); {
1194 /// break; bar();
1195 /// } break;
1196 /// default: { }
1197 /// plop(); default:
1198 /// } {
1199 /// } plop();
1200 /// }
1201 /// }
1202 /// \endcode
1204 /// Wrap class definitions.
1205 /// \code
1206 /// true:
1207 /// class foo
1208 /// {};
1209 ///
1210 /// false:
1211 /// class foo {};
1212 /// \endcode
1214
1215 /// Wrap control statements (``if``/``for``/``while``/``switch``/..).
1217 /// Wrap enum definitions.
1218 /// \code
1219 /// true:
1220 /// enum X : int
1221 /// {
1222 /// B
1223 /// };
1224 ///
1225 /// false:
1226 /// enum X : int { B };
1227 /// \endcode
1229 /// Wrap function definitions.
1230 /// \code
1231 /// true:
1232 /// void foo()
1233 /// {
1234 /// bar();
1235 /// bar2();
1236 /// }
1237 ///
1238 /// false:
1239 /// void foo() {
1240 /// bar();
1241 /// bar2();
1242 /// }
1243 /// \endcode
1245 /// Wrap namespace definitions.
1246 /// \code
1247 /// true:
1248 /// namespace
1249 /// {
1250 /// int foo();
1251 /// int bar();
1252 /// }
1253 ///
1254 /// false:
1255 /// namespace {
1256 /// int foo();
1257 /// int bar();
1258 /// }
1259 /// \endcode
1261 /// Wrap ObjC definitions (interfaces, implementations...).
1262 /// \note
1263 /// @autoreleasepool and @synchronized blocks are wrapped
1264 /// according to ``AfterControlStatement`` flag.
1265 /// \endnote
1267 /// Wrap struct definitions.
1268 /// \code
1269 /// true:
1270 /// struct foo
1271 /// {
1272 /// int x;
1273 /// };
1274 ///
1275 /// false:
1276 /// struct foo {
1277 /// int x;
1278 /// };
1279 /// \endcode
1281 /// Wrap union definitions.
1282 /// \code
1283 /// true:
1284 /// union foo
1285 /// {
1286 /// int x;
1287 /// }
1288 ///
1289 /// false:
1290 /// union foo {
1291 /// int x;
1292 /// }
1293 /// \endcode
1295 /// Wrap extern blocks.
1296 /// \code
1297 /// true:
1298 /// extern "C"
1299 /// {
1300 /// int foo();
1301 /// }
1302 ///
1303 /// false:
1304 /// extern "C" {
1305 /// int foo();
1306 /// }
1307 /// \endcode
1308 bool AfterExternBlock; // Partially superseded by IndentExternBlock
1309 /// Wrap before ``catch``.
1310 /// \code
1311 /// true:
1312 /// try {
1313 /// foo();
1314 /// }
1315 /// catch () {
1316 /// }
1317 ///
1318 /// false:
1319 /// try {
1320 /// foo();
1321 /// } catch () {
1322 /// }
1323 /// \endcode
1325 /// Wrap before ``else``.
1326 /// \code
1327 /// true:
1328 /// if (foo()) {
1329 /// }
1330 /// else {
1331 /// }
1332 ///
1333 /// false:
1334 /// if (foo()) {
1335 /// } else {
1336 /// }
1337 /// \endcode
1339 /// Wrap lambda block.
1340 /// \code
1341 /// true:
1342 /// connect(
1343 /// []()
1344 /// {
1345 /// foo();
1346 /// bar();
1347 /// });
1348 ///
1349 /// false:
1350 /// connect([]() {
1351 /// foo();
1352 /// bar();
1353 /// });
1354 /// \endcode
1356 /// Wrap before ``while``.
1357 /// \code
1358 /// true:
1359 /// do {
1360 /// foo();
1361 /// }
1362 /// while (1);
1363 ///
1364 /// false:
1365 /// do {
1366 /// foo();
1367 /// } while (1);
1368 /// \endcode
1370 /// Indent the wrapped braces themselves.
1372 /// If ``false``, empty function body can be put on a single line.
1373 /// This option is used only if the opening brace of the function has
1374 /// already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is
1375 /// set, and the function could/should not be put on a single line (as per
1376 /// ``AllowShortFunctionsOnASingleLine`` and constructor formatting
1377 /// options).
1378 /// \code
1379 /// false: true:
1380 /// int f() vs. int f()
1381 /// {} {
1382 /// }
1383 /// \endcode
1384 ///
1386 /// If ``false``, empty record (e.g. class, struct or union) body
1387 /// can be put on a single line. This option is used only if the opening
1388 /// brace of the record has already been wrapped, i.e. the ``AfterClass``
1389 /// (for classes) brace wrapping mode is set.
1390 /// \code
1391 /// false: true:
1392 /// class Foo vs. class Foo
1393 /// {} {
1394 /// }
1395 /// \endcode
1396 ///
1398 /// If ``false``, empty namespace body can be put on a single line.
1399 /// This option is used only if the opening brace of the namespace has
1400 /// already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is
1401 /// set.
1402 /// \code
1403 /// false: true:
1404 /// namespace Foo vs. namespace Foo
1405 /// {} {
1406 /// }
1407 /// \endcode
1408 ///
1410 };
1411
1412 /// Control of individual brace wrapping cases.
1413 ///
1414 /// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how
1415 /// each individual brace case should be handled. Otherwise, this is ignored.
1416 /// \code{.yaml}
1417 /// # Example of usage:
1418 /// BreakBeforeBraces: Custom
1419 /// BraceWrapping:
1420 /// AfterEnum: true
1421 /// AfterStruct: false
1422 /// SplitEmptyFunction: false
1423 /// \endcode
1424 /// \version 3.8
1426
1427 /// Break between adjacent string literals.
1428 /// \code
1429 /// true:
1430 /// return "Code"
1431 /// "\0\52\26\55\55\0"
1432 /// "x013"
1433 /// "\02\xBA";
1434 /// false:
1435 /// return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA";
1436 /// \endcode
1437 /// \version 18
1439
1440 /// Different ways to break after attributes.
1442 /// Always break after attributes.
1443 /// \code
1444 /// [[maybe_unused]]
1445 /// const int i;
1446 /// [[gnu::const]] [[maybe_unused]]
1447 /// int j;
1448 ///
1449 /// [[nodiscard]]
1450 /// inline int f();
1451 /// [[gnu::const]] [[nodiscard]]
1452 /// int g();
1453 ///
1454 /// [[likely]]
1455 /// if (a)
1456 /// f();
1457 /// else
1458 /// g();
1459 ///
1460 /// switch (b) {
1461 /// [[unlikely]]
1462 /// case 1:
1463 /// ++b;
1464 /// break;
1465 /// [[likely]]
1466 /// default:
1467 /// return;
1468 /// }
1469 /// \endcode
1471 /// Leave the line breaking after attributes as is.
1472 /// \code
1473 /// [[maybe_unused]] const int i;
1474 /// [[gnu::const]] [[maybe_unused]]
1475 /// int j;
1476 ///
1477 /// [[nodiscard]] inline int f();
1478 /// [[gnu::const]] [[nodiscard]]
1479 /// int g();
1480 ///
1481 /// [[likely]] if (a)
1482 /// f();
1483 /// else
1484 /// g();
1485 ///
1486 /// switch (b) {
1487 /// [[unlikely]] case 1:
1488 /// ++b;
1489 /// break;
1490 /// [[likely]]
1491 /// default:
1492 /// return;
1493 /// }
1494 /// \endcode
1496 /// Never break after attributes.
1497 /// \code
1498 /// [[maybe_unused]] const int i;
1499 /// [[gnu::const]] [[maybe_unused]] int j;
1500 ///
1501 /// [[nodiscard]] inline int f();
1502 /// [[gnu::const]] [[nodiscard]] int g();
1503 ///
1504 /// [[likely]] if (a)
1505 /// f();
1506 /// else
1507 /// g();
1508 ///
1509 /// switch (b) {
1510 /// [[unlikely]] case 1:
1511 /// ++b;
1512 /// break;
1513 /// [[likely]] default:
1514 /// return;
1515 /// }
1516 /// \endcode
1518 };
1519
1520 /// Break after a group of C++11 attributes before variable or function
1521 /// (including constructor/destructor) declaration/definition names or before
1522 /// control statements, i.e. ``if``, ``switch`` (including ``case`` and
1523 /// ``default`` labels), ``for``, and ``while`` statements.
1524 /// \version 16
1526
1527 /// If ``true``, clang-format will always break after a Json array ``[``
1528 /// otherwise it will scan until the closing ``]`` to determine if it should
1529 /// add newlines between elements (prettier compatible).
1530 ///
1531 /// \note
1532 /// This is currently only for formatting JSON.
1533 /// \endnote
1534 /// \code
1535 /// true: false:
1536 /// [ vs. [1, 2, 3, 4]
1537 /// 1,
1538 /// 2,
1539 /// 3,
1540 /// 4
1541 /// ]
1542 /// \endcode
1543 /// \version 16
1545
1546 /// The style of wrapping parameters on the same line (bin-packed) or
1547 /// on one line each.
1548 enum BinPackStyle : int8_t {
1549 /// Automatically determine parameter bin-packing behavior.
1551 /// Always bin-pack parameters.
1553 /// Never bin-pack parameters.
1555 };
1556
1557 /// The style of breaking before or after binary operators.
1558 enum BinaryOperatorStyle : int8_t {
1559 /// Break after operators.
1560 /// \code
1561 /// LooooooooooongType loooooooooooooooooooooongVariable =
1562 /// someLooooooooooooooooongFunction();
1563 ///
1564 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
1565 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
1566 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
1567 /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
1568 /// ccccccccccccccccccccccccccccccccccccccccc;
1569 /// \endcode
1571 /// Break before operators that aren't assignments.
1572 /// \code
1573 /// LooooooooooongType loooooooooooooooooooooongVariable =
1574 /// someLooooooooooooooooongFunction();
1575 ///
1576 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1577 /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1578 /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1579 /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1580 /// > ccccccccccccccccccccccccccccccccccccccccc;
1581 /// \endcode
1583 /// Break before operators.
1584 /// \code
1585 /// LooooooooooongType loooooooooooooooooooooongVariable
1586 /// = someLooooooooooooooooongFunction();
1587 ///
1588 /// bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1589 /// + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1590 /// == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1591 /// && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
1592 /// > ccccccccccccccccccccccccccccccccccccccccc;
1593 /// \endcode
1595 };
1596
1597 /// The way to wrap binary operators.
1598 /// \version 3.6
1600
1601 /// Different ways to attach braces to their surrounding context.
1602 enum BraceBreakingStyle : int8_t {
1603 /// Always attach braces to surrounding context.
1604 /// \code
1605 /// namespace N {
1606 /// enum E {
1607 /// E1,
1608 /// E2,
1609 /// };
1610 ///
1611 /// class C {
1612 /// public:
1613 /// C();
1614 /// };
1615 ///
1616 /// bool baz(int i) {
1617 /// try {
1618 /// do {
1619 /// switch (i) {
1620 /// case 1: {
1621 /// foobar();
1622 /// break;
1623 /// }
1624 /// default: {
1625 /// break;
1626 /// }
1627 /// }
1628 /// } while (--i);
1629 /// return true;
1630 /// } catch (...) {
1631 /// handleError();
1632 /// return false;
1633 /// }
1634 /// }
1635 ///
1636 /// void foo(bool b) {
1637 /// if (b) {
1638 /// baz(2);
1639 /// } else {
1640 /// baz(5);
1641 /// }
1642 /// }
1643 ///
1644 /// void bar() { foo(true); }
1645 /// } // namespace N
1646 /// \endcode
1648 /// Like ``Attach``, but break before braces on function, namespace and
1649 /// class definitions.
1650 /// \code
1651 /// namespace N
1652 /// {
1653 /// enum E {
1654 /// E1,
1655 /// E2,
1656 /// };
1657 ///
1658 /// class C
1659 /// {
1660 /// public:
1661 /// C();
1662 /// };
1663 ///
1664 /// bool baz(int i)
1665 /// {
1666 /// try {
1667 /// do {
1668 /// switch (i) {
1669 /// case 1: {
1670 /// foobar();
1671 /// break;
1672 /// }
1673 /// default: {
1674 /// break;
1675 /// }
1676 /// }
1677 /// } while (--i);
1678 /// return true;
1679 /// } catch (...) {
1680 /// handleError();
1681 /// return false;
1682 /// }
1683 /// }
1684 ///
1685 /// void foo(bool b)
1686 /// {
1687 /// if (b) {
1688 /// baz(2);
1689 /// } else {
1690 /// baz(5);
1691 /// }
1692 /// }
1693 ///
1694 /// void bar() { foo(true); }
1695 /// } // namespace N
1696 /// \endcode
1698 /// Like ``Attach``, but break before braces on enum, function, and record
1699 /// definitions.
1700 /// \code
1701 /// namespace N {
1702 /// enum E
1703 /// {
1704 /// E1,
1705 /// E2,
1706 /// };
1707 ///
1708 /// class C
1709 /// {
1710 /// public:
1711 /// C();
1712 /// };
1713 ///
1714 /// bool baz(int i)
1715 /// {
1716 /// try {
1717 /// do {
1718 /// switch (i) {
1719 /// case 1: {
1720 /// foobar();
1721 /// break;
1722 /// }
1723 /// default: {
1724 /// break;
1725 /// }
1726 /// }
1727 /// } while (--i);
1728 /// return true;
1729 /// } catch (...) {
1730 /// handleError();
1731 /// return false;
1732 /// }
1733 /// }
1734 ///
1735 /// void foo(bool b)
1736 /// {
1737 /// if (b) {
1738 /// baz(2);
1739 /// } else {
1740 /// baz(5);
1741 /// }
1742 /// }
1743 ///
1744 /// void bar() { foo(true); }
1745 /// } // namespace N
1746 /// \endcode
1748 /// Like ``Attach``, but break before function definitions, ``catch``, and
1749 /// ``else``.
1750 /// \code
1751 /// namespace N {
1752 /// enum E {
1753 /// E1,
1754 /// E2,
1755 /// };
1756 ///
1757 /// class C {
1758 /// public:
1759 /// C();
1760 /// };
1761 ///
1762 /// bool baz(int i)
1763 /// {
1764 /// try {
1765 /// do {
1766 /// switch (i) {
1767 /// case 1: {
1768 /// foobar();
1769 /// break;
1770 /// }
1771 /// default: {
1772 /// break;
1773 /// }
1774 /// }
1775 /// } while (--i);
1776 /// return true;
1777 /// }
1778 /// catch (...) {
1779 /// handleError();
1780 /// return false;
1781 /// }
1782 /// }
1783 ///
1784 /// void foo(bool b)
1785 /// {
1786 /// if (b) {
1787 /// baz(2);
1788 /// }
1789 /// else {
1790 /// baz(5);
1791 /// }
1792 /// }
1793 ///
1794 /// void bar() { foo(true); }
1795 /// } // namespace N
1796 /// \endcode
1798 /// Always break before braces.
1799 /// \code
1800 /// namespace N
1801 /// {
1802 /// enum E
1803 /// {
1804 /// E1,
1805 /// E2,
1806 /// };
1807 ///
1808 /// class C
1809 /// {
1810 /// public:
1811 /// C();
1812 /// };
1813 ///
1814 /// bool baz(int i)
1815 /// {
1816 /// try
1817 /// {
1818 /// do
1819 /// {
1820 /// switch (i)
1821 /// {
1822 /// case 1:
1823 /// {
1824 /// foobar();
1825 /// break;
1826 /// }
1827 /// default:
1828 /// {
1829 /// break;
1830 /// }
1831 /// }
1832 /// } while (--i);
1833 /// return true;
1834 /// }
1835 /// catch (...)
1836 /// {
1837 /// handleError();
1838 /// return false;
1839 /// }
1840 /// }
1841 ///
1842 /// void foo(bool b)
1843 /// {
1844 /// if (b)
1845 /// {
1846 /// baz(2);
1847 /// }
1848 /// else
1849 /// {
1850 /// baz(5);
1851 /// }
1852 /// }
1853 ///
1854 /// void bar() { foo(true); }
1855 /// } // namespace N
1856 /// \endcode
1858 /// Like ``Allman`` but always indent braces and line up code with braces.
1859 /// \code
1860 /// namespace N
1861 /// {
1862 /// enum E
1863 /// {
1864 /// E1,
1865 /// E2,
1866 /// };
1867 ///
1868 /// class C
1869 /// {
1870 /// public:
1871 /// C();
1872 /// };
1873 ///
1874 /// bool baz(int i)
1875 /// {
1876 /// try
1877 /// {
1878 /// do
1879 /// {
1880 /// switch (i)
1881 /// {
1882 /// case 1:
1883 /// {
1884 /// foobar();
1885 /// break;
1886 /// }
1887 /// default:
1888 /// {
1889 /// break;
1890 /// }
1891 /// }
1892 /// } while (--i);
1893 /// return true;
1894 /// }
1895 /// catch (...)
1896 /// {
1897 /// handleError();
1898 /// return false;
1899 /// }
1900 /// }
1901 ///
1902 /// void foo(bool b)
1903 /// {
1904 /// if (b)
1905 /// {
1906 /// baz(2);
1907 /// }
1908 /// else
1909 /// {
1910 /// baz(5);
1911 /// }
1912 /// }
1913 ///
1914 /// void bar() { foo(true); }
1915 /// } // namespace N
1916 /// \endcode
1918 /// Always break before braces and add an extra level of indentation to
1919 /// braces of control statements, not to those of class, function
1920 /// or other definitions.
1921 /// \code
1922 /// namespace N
1923 /// {
1924 /// enum E
1925 /// {
1926 /// E1,
1927 /// E2,
1928 /// };
1929 ///
1930 /// class C
1931 /// {
1932 /// public:
1933 /// C();
1934 /// };
1935 ///
1936 /// bool baz(int i)
1937 /// {
1938 /// try
1939 /// {
1940 /// do
1941 /// {
1942 /// switch (i)
1943 /// {
1944 /// case 1:
1945 /// {
1946 /// foobar();
1947 /// break;
1948 /// }
1949 /// default:
1950 /// {
1951 /// break;
1952 /// }
1953 /// }
1954 /// }
1955 /// while (--i);
1956 /// return true;
1957 /// }
1958 /// catch (...)
1959 /// {
1960 /// handleError();
1961 /// return false;
1962 /// }
1963 /// }
1964 ///
1965 /// void foo(bool b)
1966 /// {
1967 /// if (b)
1968 /// {
1969 /// baz(2);
1970 /// }
1971 /// else
1972 /// {
1973 /// baz(5);
1974 /// }
1975 /// }
1976 ///
1977 /// void bar() { foo(true); }
1978 /// } // namespace N
1979 /// \endcode
1981 /// Like ``Attach``, but break before functions.
1982 /// \code
1983 /// namespace N {
1984 /// enum E {
1985 /// E1,
1986 /// E2,
1987 /// };
1988 ///
1989 /// class C {
1990 /// public:
1991 /// C();
1992 /// };
1993 ///
1994 /// bool baz(int i)
1995 /// {
1996 /// try {
1997 /// do {
1998 /// switch (i) {
1999 /// case 1: {
2000 /// foobar();
2001 /// break;
2002 /// }
2003 /// default: {
2004 /// break;
2005 /// }
2006 /// }
2007 /// } while (--i);
2008 /// return true;
2009 /// } catch (...) {
2010 /// handleError();
2011 /// return false;
2012 /// }
2013 /// }
2014 ///
2015 /// void foo(bool b)
2016 /// {
2017 /// if (b) {
2018 /// baz(2);
2019 /// } else {
2020 /// baz(5);
2021 /// }
2022 /// }
2023 ///
2024 /// void bar() { foo(true); }
2025 /// } // namespace N
2026 /// \endcode
2028 /// Configure each individual brace in ``BraceWrapping``.
2029 BS_Custom
2031
2032 /// The brace breaking style to use.
2033 /// \version 3.7
2035
2036 /// Different ways to break before concept declarations.
2038 /// Keep the template declaration line together with ``concept``.
2039 /// \code
2040 /// template <typename T> concept C = ...;
2041 /// \endcode
2043 /// Breaking between template declaration and ``concept`` is allowed. The
2044 /// actual behavior depends on the content and line breaking rules and
2045 /// penalties.
2047 /// Always break before ``concept``, putting it in the line after the
2048 /// template declaration.
2049 /// \code
2050 /// template <typename T>
2051 /// concept C = ...;
2052 /// \endcode
2054 };
2055
2056 /// The concept declaration style to use.
2057 /// \version 12
2059
2060 /// Different ways to break ASM parameters.
2062 /// No break before inline ASM colon.
2063 /// \code
2064 /// asm volatile("string", : : val);
2065 /// \endcode
2067 /// Break before inline ASM colon if the line length is longer than column
2068 /// limit.
2069 /// \code
2070 /// asm volatile("string", : : val);
2071 /// asm("cmoveq %1, %2, %[result]"
2072 /// : [result] "=r"(result)
2073 /// : "r"(test), "r"(new), "[result]"(old));
2074 /// \endcode
2076 /// Always break before inline ASM colon.
2077 /// \code
2078 /// asm volatile("string",
2079 /// :
2080 /// : val);
2081 /// \endcode
2083 };
2084
2085 /// The inline ASM colon style to use.
2086 /// \version 16
2088
2089 /// If ``true``, ternary operators will be placed after line breaks.
2090 /// \code
2091 /// true:
2092 /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
2093 /// ? firstValue
2094 /// : SecondValueVeryVeryVeryVeryLong;
2095 ///
2096 /// false:
2097 /// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
2098 /// firstValue :
2099 /// SecondValueVeryVeryVeryVeryLong;
2100 /// \endcode
2101 /// \version 3.7
2103
2104 /// Different ways to break initializers.
2106 /// Break constructor initializers before the colon and after the commas.
2107 /// \code
2108 /// Constructor()
2109 /// : initializer1(),
2110 /// initializer2()
2111 /// \endcode
2113 /// Break constructor initializers before the colon and commas, and align
2114 /// the commas with the colon.
2115 /// \code
2116 /// Constructor()
2117 /// : initializer1()
2118 /// , initializer2()
2119 /// \endcode
2121 /// Break constructor initializers after the colon and commas.
2122 /// \code
2123 /// Constructor() :
2124 /// initializer1(),
2125 /// initializer2()
2126 /// \endcode
2129
2130 /// The break constructor initializers style to use.
2131 /// \version 5
2133
2134 /// Break after each annotation on a field in Java files.
2135 /// \code{.java}
2136 /// true: false:
2137 /// @Partial vs. @Partial @Mock DataLoad loader;
2138 /// @Mock
2139 /// DataLoad loader;
2140 /// \endcode
2141 /// \version 3.8
2143
2144 /// Allow breaking string literals when formatting.
2145 ///
2146 /// In C, C++, and Objective-C:
2147 /// \code
2148 /// true:
2149 /// const char* x = "veryVeryVeryVeryVeryVe"
2150 /// "ryVeryVeryVeryVeryVery"
2151 /// "VeryLongString";
2152 ///
2153 /// false:
2154 /// const char* x =
2155 /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
2156 /// \endcode
2157 ///
2158 /// In C# and Java:
2159 /// \code
2160 /// true:
2161 /// string x = "veryVeryVeryVeryVeryVe" +
2162 /// "ryVeryVeryVeryVeryVery" +
2163 /// "VeryLongString";
2164 ///
2165 /// false:
2166 /// string x =
2167 /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
2168 /// \endcode
2169 ///
2170 /// C# interpolated strings are not broken.
2171 ///
2172 /// In Verilog:
2173 /// \code
2174 /// true:
2175 /// string x = {"veryVeryVeryVeryVeryVe",
2176 /// "ryVeryVeryVeryVeryVery",
2177 /// "VeryLongString"};
2178 ///
2179 /// false:
2180 /// string x =
2181 /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
2182 /// \endcode
2183 ///
2184 /// \version 3.9
2186
2187 /// The column limit.
2188 ///
2189 /// A column limit of ``0`` means that there is no column limit. In this case,
2190 /// clang-format will respect the input's line breaking decisions within
2191 /// statements unless they contradict other rules.
2192 /// \version 3.7
2193 unsigned ColumnLimit;
2194
2195 /// A regular expression that describes comments with special meaning,
2196 /// which should not be split into lines or otherwise changed.
2197 /// \code
2198 /// // CommentPragmas: '^ FOOBAR pragma:'
2199 /// // Will leave the following line unaffected
2200 /// #include <vector> // FOOBAR pragma: keep
2201 /// \endcode
2202 /// \version 3.7
2203 std::string CommentPragmas;
2204
2205 /// Different ways to break inheritance list.
2207 /// Break inheritance list before the colon and after the commas.
2208 /// \code
2209 /// class Foo
2210 /// : Base1,
2211 /// Base2
2212 /// {};
2213 /// \endcode
2215 /// Break inheritance list before the colon and commas, and align
2216 /// the commas with the colon.
2217 /// \code
2218 /// class Foo
2219 /// : Base1
2220 /// , Base2
2221 /// {};
2222 /// \endcode
2224 /// Break inheritance list after the colon and commas.
2225 /// \code
2226 /// class Foo :
2227 /// Base1,
2228 /// Base2
2229 /// {};
2230 /// \endcode
2232 /// Break inheritance list only after the commas.
2233 /// \code
2234 /// class Foo : Base1,
2235 /// Base2
2236 /// {};
2237 /// \endcode
2239 };
2240
2241 /// The inheritance list style to use.
2242 /// \version 7
2244
2245 /// If ``true``, consecutive namespace declarations will be on the same
2246 /// line. If ``false``, each namespace is declared on a new line.
2247 /// \code
2248 /// true:
2249 /// namespace Foo { namespace Bar {
2250 /// }}
2251 ///
2252 /// false:
2253 /// namespace Foo {
2254 /// namespace Bar {
2255 /// }
2256 /// }
2257 /// \endcode
2258 ///
2259 /// If it does not fit on a single line, the overflowing namespaces get
2260 /// wrapped:
2261 /// \code
2262 /// namespace Foo { namespace Bar {
2263 /// namespace Extra {
2264 /// }}}
2265 /// \endcode
2266 /// \version 5
2268
2269 /// This option is **deprecated**. See ``CurrentLine`` of
2270 /// ``PackConstructorInitializers``.
2271 /// \version 3.7
2272 // bool ConstructorInitializerAllOnOneLineOrOnePerLine;
2273
2274 /// The number of characters to use for indentation of constructor
2275 /// initializer lists as well as inheritance lists.
2276 /// \version 3.7
2278
2279 /// Indent width for line continuations.
2280 /// \code
2281 /// ContinuationIndentWidth: 2
2282 ///
2283 /// int i = // VeryVeryVeryVeryVeryLongComment
2284 /// longFunction( // Again a long comment
2285 /// arg);
2286 /// \endcode
2287 /// \version 3.7
2289
2290 /// If ``true``, format braced lists as best suited for C++11 braced
2291 /// lists.
2292 ///
2293 /// Important differences:
2294 /// - No spaces inside the braced list.
2295 /// - No line break before the closing brace.
2296 /// - Indentation with the continuation indent, not with the block indent.
2297 ///
2298 /// Fundamentally, C++11 braced lists are formatted exactly like function
2299 /// calls would be formatted in their place. If the braced list follows a name
2300 /// (e.g. a type or variable name), clang-format formats as if the ``{}`` were
2301 /// the parentheses of a function call with that name. If there is no name,
2302 /// a zero-length name is assumed.
2303 /// \code
2304 /// true: false:
2305 /// vector<int> x{1, 2, 3, 4}; vs. vector<int> x{ 1, 2, 3, 4 };
2306 /// vector<T> x{{}, {}, {}, {}}; vector<T> x{ {}, {}, {}, {} };
2307 /// f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]);
2308 /// new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 };
2309 /// \endcode
2310 /// \version 3.4
2312
2313 /// This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of
2314 /// ``LineEnding``.
2315 /// \version 10
2316 // bool DeriveLineEnding;
2317
2318 /// If ``true``, analyze the formatted file for the most common
2319 /// alignment of ``&`` and ``*``.
2320 /// Pointer and reference alignment styles are going to be updated according
2321 /// to the preferences found in the file.
2322 /// ``PointerAlignment`` is then used only as fallback.
2323 /// \version 3.7
2325
2326 /// Disables formatting completely.
2327 /// \version 3.7
2329
2330 /// Different styles for empty line after access modifiers.
2331 /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
2332 /// empty lines between two access modifiers.
2334 /// Remove all empty lines after access modifiers.
2335 /// \code
2336 /// struct foo {
2337 /// private:
2338 /// int i;
2339 /// protected:
2340 /// int j;
2341 /// /* comment */
2342 /// public:
2343 /// foo() {}
2344 /// private:
2345 /// protected:
2346 /// };
2347 /// \endcode
2349 /// Keep existing empty lines after access modifiers.
2350 /// MaxEmptyLinesToKeep is applied instead.
2352 /// Always add empty line after access modifiers if there are none.
2353 /// MaxEmptyLinesToKeep is applied also.
2354 /// \code
2355 /// struct foo {
2356 /// private:
2357 ///
2358 /// int i;
2359 /// protected:
2360 ///
2361 /// int j;
2362 /// /* comment */
2363 /// public:
2364 ///
2365 /// foo() {}
2366 /// private:
2367 ///
2368 /// protected:
2369 ///
2370 /// };
2371 /// \endcode
2373 };
2374
2375 /// Defines when to put an empty line after access modifiers.
2376 /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
2377 /// empty lines between two access modifiers.
2378 /// \version 13
2380
2381 /// Different styles for empty line before access modifiers.
2383 /// Remove all empty lines before access modifiers.
2384 /// \code
2385 /// struct foo {
2386 /// private:
2387 /// int i;
2388 /// protected:
2389 /// int j;
2390 /// /* comment */
2391 /// public:
2392 /// foo() {}
2393 /// private:
2394 /// protected:
2395 /// };
2396 /// \endcode
2398 /// Keep existing empty lines before access modifiers.
2400 /// Add empty line only when access modifier starts a new logical block.
2401 /// Logical block is a group of one or more member fields or functions.
2402 /// \code
2403 /// struct foo {
2404 /// private:
2405 /// int i;
2406 ///
2407 /// protected:
2408 /// int j;
2409 /// /* comment */
2410 /// public:
2411 /// foo() {}
2412 ///
2413 /// private:
2414 /// protected:
2415 /// };
2416 /// \endcode
2418 /// Always add empty line before access modifiers unless access modifier
2419 /// is at the start of struct or class definition.
2420 /// \code
2421 /// struct foo {
2422 /// private:
2423 /// int i;
2424 ///
2425 /// protected:
2426 /// int j;
2427 /// /* comment */
2428 ///
2429 /// public:
2430 /// foo() {}
2431 ///
2432 /// private:
2433 ///
2434 /// protected:
2435 /// };
2436 /// \endcode
2438 };
2439
2440 /// Defines in which cases to put empty line before access modifiers.
2441 /// \version 12
2443
2444 /// If ``true``, clang-format detects whether function calls and
2445 /// definitions are formatted with one parameter per line.
2446 ///
2447 /// Each call can be bin-packed, one-per-line or inconclusive. If it is
2448 /// inconclusive, e.g. completely on one line, but a decision needs to be
2449 /// made, clang-format analyzes whether there are other bin-packed cases in
2450 /// the input file and act accordingly.
2451 ///
2452 /// \note
2453 /// This is an experimental flag, that might go away or be renamed. Do
2454 /// not use this in config files, etc. Use at your own risk.
2455 /// \endnote
2456 /// \version 3.7
2458
2459 /// If ``true``, clang-format adds missing namespace end comments for
2460 /// namespaces and fixes invalid existing ones. This doesn't affect short
2461 /// namespaces, which are controlled by ``ShortNamespaceLines``.
2462 /// \code
2463 /// true: false:
2464 /// namespace longNamespace { vs. namespace longNamespace {
2465 /// void foo(); void foo();
2466 /// void bar(); void bar();
2467 /// } // namespace a }
2468 /// namespace shortNamespace { namespace shortNamespace {
2469 /// void baz(); void baz();
2470 /// } }
2471 /// \endcode
2472 /// \version 5
2474
2475 /// A vector of macros that should be interpreted as foreach loops
2476 /// instead of as function calls.
2477 ///
2478 /// These are expected to be macros of the form:
2479 /// \code
2480 /// FOREACH(<variable-declaration>, ...)
2481 /// <loop-body>
2482 /// \endcode
2483 ///
2484 /// In the .clang-format configuration file, this can be configured like:
2485 /// \code{.yaml}
2486 /// ForEachMacros: ['RANGES_FOR', 'FOREACH']
2487 /// \endcode
2488 ///
2489 /// For example: BOOST_FOREACH.
2490 /// \version 3.7
2491 std::vector<std::string> ForEachMacros;
2492
2494
2495 /// A vector of macros that should be interpreted as conditionals
2496 /// instead of as function calls.
2497 ///
2498 /// These are expected to be macros of the form:
2499 /// \code
2500 /// IF(...)
2501 /// <conditional-body>
2502 /// else IF(...)
2503 /// <conditional-body>
2504 /// \endcode
2505 ///
2506 /// In the .clang-format configuration file, this can be configured like:
2507 /// \code{.yaml}
2508 /// IfMacros: ['IF']
2509 /// \endcode
2510 ///
2511 /// For example: `KJ_IF_MAYBE
2512 /// <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
2513 /// \version 13
2514 std::vector<std::string> IfMacros;
2515
2516 /// Specify whether access modifiers should have their own indentation level.
2517 ///
2518 /// When ``false``, access modifiers are indented (or outdented) relative to
2519 /// the record members, respecting the ``AccessModifierOffset``. Record
2520 /// members are indented one level below the record.
2521 /// When ``true``, access modifiers get their own indentation level. As a
2522 /// consequence, record members are always indented 2 levels below the record,
2523 /// regardless of the access modifier presence. Value of the
2524 /// ``AccessModifierOffset`` is ignored.
2525 /// \code
2526 /// false: true:
2527 /// class C { vs. class C {
2528 /// class D { class D {
2529 /// void bar(); void bar();
2530 /// protected: protected:
2531 /// D(); D();
2532 /// }; };
2533 /// public: public:
2534 /// C(); C();
2535 /// }; };
2536 /// void foo() { void foo() {
2537 /// return 1; return 1;
2538 /// } }
2539 /// \endcode
2540 /// \version 13
2542
2543 /// Indent case label blocks one level from the case label.
2544 ///
2545 /// When ``false``, the block following the case label uses the same
2546 /// indentation level as for the case label, treating the case label the same
2547 /// as an if-statement.
2548 /// When ``true``, the block gets indented as a scope block.
2549 /// \code
2550 /// false: true:
2551 /// switch (fool) { vs. switch (fool) {
2552 /// case 1: { case 1:
2553 /// bar(); {
2554 /// } break; bar();
2555 /// default: { }
2556 /// plop(); break;
2557 /// } default:
2558 /// } {
2559 /// plop();
2560 /// }
2561 /// }
2562 /// \endcode
2563 /// \version 11
2565
2566 /// Indent case labels one level from the switch statement.
2567 ///
2568 /// When ``false``, use the same indentation level as for the switch
2569 /// statement. Switch statement body is always indented one level more than
2570 /// case labels (except the first block following the case label, which
2571 /// itself indents the code - unless IndentCaseBlocks is enabled).
2572 /// \code
2573 /// false: true:
2574 /// switch (fool) { vs. switch (fool) {
2575 /// case 1: case 1:
2576 /// bar(); bar();
2577 /// break; break;
2578 /// default: default:
2579 /// plop(); plop();
2580 /// } }
2581 /// \endcode
2582 /// \version 3.3
2584
2585 /// Indent goto labels.
2586 ///
2587 /// When ``false``, goto labels are flushed left.
2588 /// \code
2589 /// true: false:
2590 /// int f() { vs. int f() {
2591 /// if (foo()) { if (foo()) {
2592 /// label1: label1:
2593 /// bar(); bar();
2594 /// } }
2595 /// label2: label2:
2596 /// return 1; return 1;
2597 /// } }
2598 /// \endcode
2599 /// \version 10
2601
2602 /// Indents extern blocks
2604 /// Backwards compatible with AfterExternBlock's indenting.
2605 /// \code
2606 /// IndentExternBlock: AfterExternBlock
2607 /// BraceWrapping.AfterExternBlock: true
2608 /// extern "C"
2609 /// {
2610 /// void foo();
2611 /// }
2612 /// \endcode
2613 ///
2614 /// \code
2615 /// IndentExternBlock: AfterExternBlock
2616 /// BraceWrapping.AfterExternBlock: false
2617 /// extern "C" {
2618 /// void foo();
2619 /// }
2620 /// \endcode
2622 /// Does not indent extern blocks.
2623 /// \code
2624 /// extern "C" {
2625 /// void foo();
2626 /// }
2627 /// \endcode
2629 /// Indents extern blocks.
2630 /// \code
2631 /// extern "C" {
2632 /// void foo();
2633 /// }
2634 /// \endcode
2636 };
2637
2638 /// IndentExternBlockStyle is the type of indenting of extern blocks.
2639 /// \version 11
2641
2642 /// Options for indenting preprocessor directives.
2644 /// Does not indent any directives.
2645 /// \code
2646 /// #if FOO
2647 /// #if BAR
2648 /// #include <foo>
2649 /// #endif
2650 /// #endif
2651 /// \endcode
2653 /// Indents directives after the hash.
2654 /// \code
2655 /// #if FOO
2656 /// # if BAR
2657 /// # include <foo>
2658 /// # endif
2659 /// #endif
2660 /// \endcode
2662 /// Indents directives before the hash.
2663 /// \code
2664 /// #if FOO
2665 /// #if BAR
2666 /// #include <foo>
2667 /// #endif
2668 /// #endif
2669 /// \endcode
2672
2673 /// The preprocessor directive indenting style to use.
2674 /// \version 6
2676
2677 /// Indent the requires clause in a template. This only applies when
2678 /// ``RequiresClausePosition`` is ``OwnLine``, or ``WithFollowing``.
2679 ///
2680 /// In clang-format 12, 13 and 14 it was named ``IndentRequires``.
2681 /// \code
2682 /// true:
2683 /// template <typename It>
2684 /// requires Iterator<It>
2685 /// void sort(It begin, It end) {
2686 /// //....
2687 /// }
2688 ///
2689 /// false:
2690 /// template <typename It>
2691 /// requires Iterator<It>
2692 /// void sort(It begin, It end) {
2693 /// //....
2694 /// }
2695 /// \endcode
2696 /// \version 15
2698
2699 /// The number of columns to use for indentation.
2700 /// \code
2701 /// IndentWidth: 3
2702 ///
2703 /// void f() {
2704 /// someFunction();
2705 /// if (true, false) {
2706 /// f();
2707 /// }
2708 /// }
2709 /// \endcode
2710 /// \version 3.7
2711 unsigned IndentWidth;
2712
2713 /// Indent if a function definition or declaration is wrapped after the
2714 /// type.
2715 /// \code
2716 /// true:
2717 /// LoooooooooooooooooooooooooooooooooooooooongReturnType
2718 /// LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2719 ///
2720 /// false:
2721 /// LoooooooooooooooooooooooooooooooooooooooongReturnType
2722 /// LoooooooooooooooooooooooooooooooongFunctionDeclaration();
2723 /// \endcode
2724 /// \version 3.7
2726
2727 /// Insert braces after control statements (``if``, ``else``, ``for``, ``do``,
2728 /// and ``while``) in C++ unless the control statements are inside macro
2729 /// definitions or the braces would enclose preprocessor directives.
2730 /// \warning
2731 /// Setting this option to ``true`` could lead to incorrect code formatting
2732 /// due to clang-format's lack of complete semantic information. As such,
2733 /// extra care should be taken to review code changes made by this option.
2734 /// \endwarning
2735 /// \code
2736 /// false: true:
2737 ///
2738 /// if (isa<FunctionDecl>(D)) vs. if (isa<FunctionDecl>(D)) {
2739 /// handleFunctionDecl(D); handleFunctionDecl(D);
2740 /// else if (isa<VarDecl>(D)) } else if (isa<VarDecl>(D)) {
2741 /// handleVarDecl(D); handleVarDecl(D);
2742 /// else } else {
2743 /// return; return;
2744 /// }
2745 ///
2746 /// while (i--) vs. while (i--) {
2747 /// for (auto *A : D.attrs()) for (auto *A : D.attrs()) {
2748 /// handleAttr(A); handleAttr(A);
2749 /// }
2750 /// }
2751 ///
2752 /// do vs. do {
2753 /// --i; --i;
2754 /// while (i); } while (i);
2755 /// \endcode
2756 /// \version 15
2758
2759 /// Insert a newline at end of file if missing.
2760 /// \version 16
2762
2763 /// The style of inserting trailing commas into container literals.
2764 enum TrailingCommaStyle : int8_t {
2765 /// Do not insert trailing commas.
2767 /// Insert trailing commas in container literals that were wrapped over
2768 /// multiple lines. Note that this is conceptually incompatible with
2769 /// bin-packing, because the trailing comma is used as an indicator
2770 /// that a container should be formatted one-per-line (i.e. not bin-packed).
2771 /// So inserting a trailing comma counteracts bin-packing.
2773 };
2774
2775 /// If set to ``TCS_Wrapped`` will insert trailing commas in container
2776 /// literals (arrays and objects) that wrap across multiple lines.
2777 /// It is currently only available for JavaScript
2778 /// and disabled by default ``TCS_None``.
2779 /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
2780 /// as inserting the comma disables bin-packing.
2781 /// \code
2782 /// TSC_Wrapped:
2783 /// const someArray = [
2784 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
2785 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
2786 /// aaaaaaaaaaaaaaaaaaaaaaaaaa,
2787 /// // ^ inserted
2788 /// ]
2789 /// \endcode
2790 /// \version 11
2792
2793 /// Separator format of integer literals of different bases.
2794 ///
2795 /// If negative, remove separators. If ``0``, leave the literal as is. If
2796 /// positive, insert separators between digits starting from the rightmost
2797 /// digit.
2798 ///
2799 /// For example, the config below will leave separators in binary literals
2800 /// alone, insert separators in decimal literals to separate the digits into
2801 /// groups of 3, and remove separators in hexadecimal literals.
2802 /// \code
2803 /// IntegerLiteralSeparator:
2804 /// Binary: 0
2805 /// Decimal: 3
2806 /// Hex: -1
2807 /// \endcode
2808 ///
2809 /// You can also specify a minimum number of digits (``BinaryMinDigits``,
2810 /// ``DecimalMinDigits``, and ``HexMinDigits``) the integer literal must
2811 /// have in order for the separators to be inserted.
2813 /// Format separators in binary literals.
2814 /// \code{.text}
2815 /// /* -1: */ b = 0b100111101101;
2816 /// /* 0: */ b = 0b10011'11'0110'1;
2817 /// /* 3: */ b = 0b100'111'101'101;
2818 /// /* 4: */ b = 0b1001'1110'1101;
2819 /// \endcode
2820 int8_t Binary;
2821 /// Format separators in binary literals with a minimum number of digits.
2822 /// \code{.text}
2823 /// // Binary: 3
2824 /// // BinaryMinDigits: 7
2825 /// b1 = 0b101101;
2826 /// b2 = 0b1'101'101;
2827 /// \endcode
2829 /// Format separators in decimal literals.
2830 /// \code{.text}
2831 /// /* -1: */ d = 18446744073709550592ull;
2832 /// /* 0: */ d = 184467'440737'0'95505'92ull;
2833 /// /* 3: */ d = 18'446'744'073'709'550'592ull;
2834 /// \endcode
2835 int8_t Decimal;
2836 /// Format separators in decimal literals with a minimum number of digits.
2837 /// \code{.text}
2838 /// // Decimal: 3
2839 /// // DecimalMinDigits: 5
2840 /// d1 = 2023;
2841 /// d2 = 10'000;
2842 /// \endcode
2844 /// Format separators in hexadecimal literals.
2845 /// \code{.text}
2846 /// /* -1: */ h = 0xDEADBEEFDEADBEEFuz;
2847 /// /* 0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz;
2848 /// /* 2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz;
2849 /// \endcode
2850 int8_t Hex;
2851 /// Format separators in hexadecimal literals with a minimum number of
2852 /// digits.
2853 /// \code{.text}
2854 /// // Hex: 2
2855 /// // HexMinDigits: 6
2856 /// h1 = 0xABCDE;
2857 /// h2 = 0xAB'CD'EF;
2858 /// \endcode
2861 return Binary == R.Binary && BinaryMinDigits == R.BinaryMinDigits &&
2863 Hex == R.Hex && HexMinDigits == R.HexMinDigits;
2864 }
2865 };
2866
2867 /// Format integer literal separators (``'`` for C++ and ``_`` for C#, Java,
2868 /// and JavaScript).
2869 /// \version 16
2871
2872 /// A vector of prefixes ordered by the desired groups for Java imports.
2873 ///
2874 /// One group's prefix can be a subset of another - the longest prefix is
2875 /// always matched. Within a group, the imports are ordered lexicographically.
2876 /// Static imports are grouped separately and follow the same group rules.
2877 /// By default, static imports are placed before non-static imports,
2878 /// but this behavior is changed by another option,
2879 /// ``SortJavaStaticImport``.
2880 ///
2881 /// In the .clang-format configuration file, this can be configured like
2882 /// in the following yaml example. This will result in imports being
2883 /// formatted as in the Java example below.
2884 /// \code{.yaml}
2885 /// JavaImportGroups: ['com.example', 'com', 'org']
2886 /// \endcode
2887 ///
2888 /// \code{.java}
2889 /// import static com.example.function1;
2890 ///
2891 /// import static com.test.function2;
2892 ///
2893 /// import static org.example.function3;
2894 ///
2895 /// import com.example.ClassA;
2896 /// import com.example.Test;
2897 /// import com.example.a.ClassB;
2898 ///
2899 /// import com.test.ClassC;
2900 ///
2901 /// import org.example.ClassD;
2902 /// \endcode
2903 /// \version 8
2904 std::vector<std::string> JavaImportGroups;
2905
2906 /// Quotation styles for JavaScript strings. Does not affect template
2907 /// strings.
2908 enum JavaScriptQuoteStyle : int8_t {
2909 /// Leave string quotes as they are.
2910 /// \code{.js}
2911 /// string1 = "foo";
2912 /// string2 = 'bar';
2913 /// \endcode
2915 /// Always use single quotes.
2916 /// \code{.js}
2917 /// string1 = 'foo';
2918 /// string2 = 'bar';
2919 /// \endcode
2921 /// Always use double quotes.
2922 /// \code{.js}
2923 /// string1 = "foo";
2924 /// string2 = "bar";
2925 /// \endcode
2928
2929 /// The JavaScriptQuoteStyle to use for JavaScript strings.
2930 /// \version 3.9
2932
2933 // clang-format off
2934 /// Whether to wrap JavaScript import/export statements.
2935 /// \code{.js}
2936 /// true:
2937 /// import {
2938 /// VeryLongImportsAreAnnoying,
2939 /// VeryLongImportsAreAnnoying,
2940 /// VeryLongImportsAreAnnoying,
2941 /// } from 'some/module.js'
2942 ///
2943 /// false:
2944 /// import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
2945 /// \endcode
2946 /// \version 3.9
2948 // clang-format on
2949
2950 /// Keep empty lines (up to ``MaxEmptyLinesToKeep``) at end of file.
2951 /// \version 17
2953
2954 /// If true, the empty line at the start of blocks is kept.
2955 /// \code
2956 /// true: false:
2957 /// if (foo) { vs. if (foo) {
2958 /// bar();
2959 /// bar(); }
2960 /// }
2961 /// \endcode
2962 /// \version 3.7
2964
2965 /// Indentation logic for lambda bodies.
2967 /// Align lambda body relative to the lambda signature. This is the default.
2968 /// \code
2969 /// someMethod(
2970 /// [](SomeReallyLongLambdaSignatureArgument foo) {
2971 /// return;
2972 /// });
2973 /// \endcode
2975 /// For statements within block scope, align lambda body relative to the
2976 /// indentation level of the outer scope the lambda signature resides in.
2977 /// \code
2978 /// someMethod(
2979 /// [](SomeReallyLongLambdaSignatureArgument foo) {
2980 /// return;
2981 /// });
2982 ///
2983 /// someMethod(someOtherMethod(
2984 /// [](SomeReallyLongLambdaSignatureArgument foo) {
2985 /// return;
2986 /// }));
2987 /// \endcode
2989 };
2990
2991 /// The indentation style of lambda bodies. ``Signature`` (the default)
2992 /// causes the lambda body to be indented one additional level relative to
2993 /// the indentation level of the signature. ``OuterScope`` forces the lambda
2994 /// body to be indented one additional level relative to the parent scope
2995 /// containing the lambda signature.
2996 /// \version 13
2998
2999 /// Supported languages.
3000 ///
3001 /// When stored in a configuration file, specifies the language, that the
3002 /// configuration targets. When passed to the ``reformat()`` function, enables
3003 /// syntax features specific to the language.
3004 enum LanguageKind : int8_t {
3005 /// Do not use.
3007 /// Should be used for C, C++.
3009 /// Should be used for C#.
3011 /// Should be used for Java.
3013 /// Should be used for JavaScript.
3015 /// Should be used for JSON.
3017 /// Should be used for Objective-C, Objective-C++.
3019 /// Should be used for Protocol Buffers
3020 /// (https://developers.google.com/protocol-buffers/).
3022 /// Should be used for TableGen code.
3024 /// Should be used for Protocol Buffer messages in text format
3025 /// (https://developers.google.com/protocol-buffers/).
3027 /// Should be used for Verilog and SystemVerilog.
3028 /// https://standards.ieee.org/ieee/1800/6700/
3029 /// https://sci-hub.st/10.1109/IEEESTD.2018.8299595
3032 bool isCpp() const { return Language == LK_Cpp || Language == LK_ObjC; }
3033 bool isCSharp() const { return Language == LK_CSharp; }
3034 bool isJson() const { return Language == LK_Json; }
3035 bool isJavaScript() const { return Language == LK_JavaScript; }
3036 bool isVerilog() const { return Language == LK_Verilog; }
3037 bool isProto() const {
3038 return Language == LK_Proto || Language == LK_TextProto;
3039 }
3040
3041 /// Language, this format style is targeted at.
3042 /// \version 3.5
3044
3045 /// Line ending style.
3046 enum LineEndingStyle : int8_t {
3047 /// Use ``\n``.
3049 /// Use ``\r\n``.
3051 /// Use ``\n`` unless the input has more lines ending in ``\r\n``.
3053 /// Use ``\r\n`` unless the input has more lines ending in ``\n``.
3055 };
3056
3057 /// Line ending style (``\n`` or ``\r\n``) to use.
3058 /// \version 16
3060
3061 /// A regular expression matching macros that start a block.
3062 /// \code
3063 /// # With:
3064 /// MacroBlockBegin: "^NS_MAP_BEGIN|\
3065 /// NS_TABLE_HEAD$"
3066 /// MacroBlockEnd: "^\
3067 /// NS_MAP_END|\
3068 /// NS_TABLE_.*_END$"
3069 ///
3070 /// NS_MAP_BEGIN
3071 /// foo();
3072 /// NS_MAP_END
3073 ///
3074 /// NS_TABLE_HEAD
3075 /// bar();
3076 /// NS_TABLE_FOO_END
3077 ///
3078 /// # Without:
3079 /// NS_MAP_BEGIN
3080 /// foo();
3081 /// NS_MAP_END
3082 ///
3083 /// NS_TABLE_HEAD
3084 /// bar();
3085 /// NS_TABLE_FOO_END
3086 /// \endcode
3087 /// \version 3.7
3088 std::string MacroBlockBegin;
3089
3090 /// A regular expression matching macros that end a block.
3091 /// \version 3.7
3092 std::string MacroBlockEnd;
3093
3094 /// A list of macros of the form \c <definition>=<expansion> .
3095 ///
3096 /// Code will be parsed with macros expanded, in order to determine how to
3097 /// interpret and format the macro arguments.
3098 ///
3099 /// For example, the code:
3100 /// \code
3101 /// A(a*b);
3102 /// \endcode
3103 ///
3104 /// will usually be interpreted as a call to a function A, and the
3105 /// multiplication expression will be formatted as ``a * b``.
3106 ///
3107 /// If we specify the macro definition:
3108 /// \code{.yaml}
3109 /// Macros:
3110 /// - A(x)=x
3111 /// \endcode
3112 ///
3113 /// the code will now be parsed as a declaration of the variable b of type a*,
3114 /// and formatted as ``a* b`` (depending on pointer-binding rules).
3115 ///
3116 /// Features and restrictions:
3117 /// * Both function-like macros and object-like macros are supported.
3118 /// * Macro arguments must be used exactly once in the expansion.
3119 /// * No recursive expansion; macros referencing other macros will be
3120 /// ignored.
3121 /// * Overloading by arity is supported: for example, given the macro
3122 /// definitions A=x, A()=y, A(a)=a
3123 ///
3124 /// \code
3125 /// A; -> x;
3126 /// A(); -> y;
3127 /// A(z); -> z;
3128 /// A(a, b); // will not be expanded.
3129 /// \endcode
3130 ///
3131 /// \version 17
3132 std::vector<std::string> Macros;
3133
3134 /// The maximum number of consecutive empty lines to keep.
3135 /// \code
3136 /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
3137 /// int f() { int f() {
3138 /// int = 1; int i = 1;
3139 /// i = foo();
3140 /// i = foo(); return i;
3141 /// }
3142 /// return i;
3143 /// }
3144 /// \endcode
3145 /// \version 3.7
3147
3148 /// Different ways to indent namespace contents.
3150 /// Don't indent in namespaces.
3151 /// \code
3152 /// namespace out {
3153 /// int i;
3154 /// namespace in {
3155 /// int i;
3156 /// }
3157 /// }
3158 /// \endcode
3160 /// Indent only in inner namespaces (nested in other namespaces).
3161 /// \code
3162 /// namespace out {
3163 /// int i;
3164 /// namespace in {
3165 /// int i;
3166 /// }
3167 /// }
3168 /// \endcode
3170 /// Indent in all namespaces.
3171 /// \code
3172 /// namespace out {
3173 /// int i;
3174 /// namespace in {
3175 /// int i;
3176 /// }
3177 /// }
3178 /// \endcode
3179 NI_All
3181
3182 /// The indentation used for namespaces.
3183 /// \version 3.7
3185
3186 /// A vector of macros which are used to open namespace blocks.
3187 ///
3188 /// These are expected to be macros of the form:
3189 /// \code
3190 /// NAMESPACE(<namespace-name>, ...) {
3191 /// <namespace-content>
3192 /// }
3193 /// \endcode
3194 ///
3195 /// For example: TESTSUITE
3196 /// \version 9
3197 std::vector<std::string> NamespaceMacros;
3198
3199 /// Controls bin-packing Objective-C protocol conformance list
3200 /// items into as few lines as possible when they go over ``ColumnLimit``.
3201 ///
3202 /// If ``Auto`` (the default), delegates to the value in
3203 /// ``BinPackParameters``. If that is ``true``, bin-packs Objective-C
3204 /// protocol conformance list items into as few lines as possible
3205 /// whenever they go over ``ColumnLimit``.
3206 ///
3207 /// If ``Always``, always bin-packs Objective-C protocol conformance
3208 /// list items into as few lines as possible whenever they go over
3209 /// ``ColumnLimit``.
3210 ///
3211 /// If ``Never``, lays out Objective-C protocol conformance list items
3212 /// onto individual lines whenever they go over ``ColumnLimit``.
3213 ///
3214 /// \code{.objc}
3215 /// Always (or Auto, if BinPackParameters=true):
3216 /// @interface ccccccccccccc () <
3217 /// ccccccccccccc, ccccccccccccc,
3218 /// ccccccccccccc, ccccccccccccc> {
3219 /// }
3220 ///
3221 /// Never (or Auto, if BinPackParameters=false):
3222 /// @interface ddddddddddddd () <
3223 /// ddddddddddddd,
3224 /// ddddddddddddd,
3225 /// ddddddddddddd,
3226 /// ddddddddddddd> {
3227 /// }
3228 /// \endcode
3229 /// \version 7
3231
3232 /// The number of characters to use for indentation of ObjC blocks.
3233 /// \code{.objc}
3234 /// ObjCBlockIndentWidth: 4
3235 ///
3236 /// [operation setCompletionBlock:^{
3237 /// [self onOperationDone];
3238 /// }];
3239 /// \endcode
3240 /// \version 3.7
3242
3243 /// Break parameters list into lines when there is nested block
3244 /// parameters in a function call.
3245 /// \code
3246 /// false:
3247 /// - (void)_aMethod
3248 /// {
3249 /// [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
3250 /// *u, NSNumber *v) {
3251 /// u = c;
3252 /// }]
3253 /// }
3254 /// true:
3255 /// - (void)_aMethod
3256 /// {
3257 /// [self.test1 t:self
3258 /// w:self
3259 /// callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
3260 /// u = c;
3261 /// }]
3262 /// }
3263 /// \endcode
3264 /// \version 11
3266
3267 /// The order in which ObjC property attributes should appear.
3268 ///
3269 /// Attributes in code will be sorted in the order specified. Any attributes
3270 /// encountered that are not mentioned in this array will be sorted last, in
3271 /// stable order. Comments between attributes will leave the attributes
3272 /// untouched.
3273 /// \warning
3274 /// Using this option could lead to incorrect code formatting due to
3275 /// clang-format's lack of complete semantic information. As such, extra
3276 /// care should be taken to review code changes made by this option.
3277 /// \endwarning
3278 /// \code{.yaml}
3279 /// ObjCPropertyAttributeOrder: [
3280 /// class, direct,
3281 /// atomic, nonatomic,
3282 /// assign, retain, strong, copy, weak, unsafe_unretained,
3283 /// readonly, readwrite, getter, setter,
3284 /// nullable, nonnull, null_resettable, null_unspecified
3285 /// ]
3286 /// \endcode
3287 /// \version 18
3288 std::vector<std::string> ObjCPropertyAttributeOrder;
3289
3290 /// Add a space after ``@property`` in Objective-C, i.e. use
3291 /// ``@property (readonly)`` instead of ``@property(readonly)``.
3292 /// \version 3.7
3294
3295 /// Add a space in front of an Objective-C protocol list, i.e. use
3296 /// ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
3297 /// \version 3.7
3299
3300 /// Different ways to try to fit all constructor initializers on a line.
3302 /// Always put each constructor initializer on its own line.
3303 /// \code
3304 /// Constructor()
3305 /// : a(),
3306 /// b()
3307 /// \endcode
3309 /// Bin-pack constructor initializers.
3310 /// \code
3311 /// Constructor()
3312 /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(),
3313 /// cccccccccccccccccccc()
3314 /// \endcode
3316 /// Put all constructor initializers on the current line if they fit.
3317 /// Otherwise, put each one on its own line.
3318 /// \code
3319 /// Constructor() : a(), b()
3320 ///
3321 /// Constructor()
3322 /// : aaaaaaaaaaaaaaaaaaaa(),
3323 /// bbbbbbbbbbbbbbbbbbbb(),
3324 /// ddddddddddddd()
3325 /// \endcode
3327 /// Same as ``PCIS_CurrentLine`` except that if all constructor initializers
3328 /// do not fit on the current line, try to fit them on the next line.
3329 /// \code
3330 /// Constructor() : a(), b()
3331 ///
3332 /// Constructor()
3333 /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
3334 ///
3335 /// Constructor()
3336 /// : aaaaaaaaaaaaaaaaaaaa(),
3337 /// bbbbbbbbbbbbbbbbbbbb(),
3338 /// cccccccccccccccccccc()
3339 /// \endcode
3341 /// Put all constructor initializers on the next line if they fit.
3342 /// Otherwise, put each one on its own line.
3343 /// \code
3344 /// Constructor()
3345 /// : a(), b()
3346 ///
3347 /// Constructor()
3348 /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
3349 ///
3350 /// Constructor()
3351 /// : aaaaaaaaaaaaaaaaaaaa(),
3352 /// bbbbbbbbbbbbbbbbbbbb(),
3353 /// cccccccccccccccccccc()
3354 /// \endcode
3356 };
3357
3358 /// The pack constructor initializers style to use.
3359 /// \version 14
3361
3362 /// The penalty for breaking around an assignment operator.
3363 /// \version 5
3365
3366 /// The penalty for breaking a function call after ``call(``.
3367 /// \version 3.7
3369
3370 /// The penalty for each line break introduced inside a comment.
3371 /// \version 3.7
3373
3374 /// The penalty for breaking before the first ``<<``.
3375 /// \version 3.7
3377
3378 /// The penalty for breaking after ``(``.
3379 /// \version 14
3381
3382 /// The penalty for each line break introduced inside a string literal.
3383 /// \version 3.7
3385
3386 /// The penalty for breaking after template declaration.
3387 /// \version 7
3389
3390 /// The penalty for each character outside of the column limit.
3391 /// \version 3.7
3393
3394 /// Penalty for each character of whitespace indentation
3395 /// (counted relative to leading non-whitespace column).
3396 /// \version 12
3398
3399 /// Penalty for putting the return type of a function onto its own line.
3400 /// \version 3.7
3402
3403 /// The ``&``, ``&&`` and ``*`` alignment style.
3405 /// Align pointer to the left.
3406 /// \code
3407 /// int* a;
3408 /// \endcode
3410 /// Align pointer to the right.
3411 /// \code
3412 /// int *a;
3413 /// \endcode
3415 /// Align pointer in the middle.
3416 /// \code
3417 /// int * a;
3418 /// \endcode
3421
3422 /// Pointer and reference alignment style.
3423 /// \version 3.7
3425
3426 /// The number of columns to use for indentation of preprocessor statements.
3427 /// When set to -1 (default) ``IndentWidth`` is used also for preprocessor
3428 /// statements.
3429 /// \code
3430 /// PPIndentWidth: 1
3431 ///
3432 /// #ifdef __linux__
3433 /// # define FOO
3434 /// #else
3435 /// # define BAR
3436 /// #endif
3437 /// \endcode
3438 /// \version 13
3440
3441 /// Different specifiers and qualifiers alignment styles.
3443 /// Don't change specifiers/qualifiers to either Left or Right alignment
3444 /// (default).
3445 /// \code
3446 /// int const a;
3447 /// const int *a;
3448 /// \endcode
3450 /// Change specifiers/qualifiers to be left-aligned.
3451 /// \code
3452 /// const int a;
3453 /// const int *a;
3454 /// \endcode
3456 /// Change specifiers/qualifiers to be right-aligned.
3457 /// \code
3458 /// int const a;
3459 /// int const *a;
3460 /// \endcode
3462 /// Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
3463 /// With:
3464 /// \code{.yaml}
3465 /// QualifierOrder: ['inline', 'static', 'type', 'const']
3466 /// \endcode
3467 ///
3468 /// \code
3469 ///
3470 /// int const a;
3471 /// int const *a;
3472 /// \endcode
3475
3476 /// Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
3477 /// \warning
3478 /// Setting ``QualifierAlignment`` to something other than ``Leave``, COULD
3479 /// lead to incorrect code formatting due to incorrect decisions made due to
3480 /// clang-formats lack of complete semantic information.
3481 /// As such extra care should be taken to review code changes made by the use
3482 /// of this option.
3483 /// \endwarning
3484 /// \version 14
3486
3487 /// The order in which the qualifiers appear.
3488 /// Order is an array that can contain any of the following:
3489 ///
3490 /// * const
3491 /// * inline
3492 /// * static
3493 /// * friend
3494 /// * constexpr
3495 /// * volatile
3496 /// * restrict
3497 /// * type
3498 ///
3499 /// \note
3500 /// it MUST contain 'type'.
3501 /// \endnote
3502 ///
3503 /// Items to the left of 'type' will be placed to the left of the type and
3504 /// aligned in the order supplied. Items to the right of 'type' will be
3505 /// placed to the right of the type and aligned in the order supplied.
3506 ///
3507 /// \code{.yaml}
3508 /// QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ]
3509 /// \endcode
3510 /// \version 14
3511 std::vector<std::string> QualifierOrder;
3512
3513 /// See documentation of ``RawStringFormats``.
3515 /// The language of this raw string.
3517 /// A list of raw string delimiters that match this language.
3518 std::vector<std::string> Delimiters;
3519 /// A list of enclosing function names that match this language.
3520 std::vector<std::string> EnclosingFunctions;
3521 /// The canonical delimiter for this language.
3523 /// The style name on which this raw string format is based on.
3524 /// If not specified, the raw string format is based on the style that this
3525 /// format is based on.
3526 std::string BasedOnStyle;
3527 bool operator==(const RawStringFormat &Other) const {
3528 return Language == Other.Language && Delimiters == Other.Delimiters &&
3529 EnclosingFunctions == Other.EnclosingFunctions &&
3530 CanonicalDelimiter == Other.CanonicalDelimiter &&
3531 BasedOnStyle == Other.BasedOnStyle;
3532 }
3533 };
3534
3535 /// Defines hints for detecting supported languages code blocks in raw
3536 /// strings.
3537 ///
3538 /// A raw string with a matching delimiter or a matching enclosing function
3539 /// name will be reformatted assuming the specified language based on the
3540 /// style for that language defined in the .clang-format file. If no style has
3541 /// been defined in the .clang-format file for the specific language, a
3542 /// predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
3543 /// found, the formatting is based on llvm style. A matching delimiter takes
3544 /// precedence over a matching enclosing function name for determining the
3545 /// language of the raw string contents.
3546 ///
3547 /// If a canonical delimiter is specified, occurrences of other delimiters for
3548 /// the same language will be updated to the canonical if possible.
3549 ///
3550 /// There should be at most one specification per language and each delimiter
3551 /// and enclosing function should not occur in multiple specifications.
3552 ///
3553 /// To configure this in the .clang-format file, use:
3554 /// \code{.yaml}
3555 /// RawStringFormats:
3556 /// - Language: TextProto
3557 /// Delimiters:
3558 /// - 'pb'
3559 /// - 'proto'
3560 /// EnclosingFunctions:
3561 /// - 'PARSE_TEXT_PROTO'
3562 /// BasedOnStyle: google
3563 /// - Language: Cpp
3564 /// Delimiters:
3565 /// - 'cc'
3566 /// - 'cpp'
3567 /// BasedOnStyle: llvm
3568 /// CanonicalDelimiter: 'cc'
3569 /// \endcode
3570 /// \version 6
3571 std::vector<RawStringFormat> RawStringFormats;
3572
3573 /// \brief The ``&`` and ``&&`` alignment style.
3575 /// Align reference like ``PointerAlignment``.
3577 /// Align reference to the left.
3578 /// \code
3579 /// int& a;
3580 /// \endcode
3582 /// Align reference to the right.
3583 /// \code
3584 /// int &a;
3585 /// \endcode
3587 /// Align reference in the middle.
3588 /// \code
3589 /// int & a;
3590 /// \endcode
3593
3594 /// \brief Reference alignment style (overrides ``PointerAlignment`` for
3595 /// references).
3596 /// \version 13
3598
3599 // clang-format off
3600 /// If ``true``, clang-format will attempt to re-flow comments. That is it
3601 /// will touch a comment and *reflow* long comments into new lines, trying to
3602 /// obey the ``ColumnLimit``.
3603 /// \code
3604 /// false:
3605 /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
3606 /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
3607 ///
3608 /// true:
3609 /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
3610 /// // information
3611 /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
3612 /// * information */
3613 /// \endcode
3614 /// \version 3.8
3616 // clang-format on
3617
3618 /// Remove optional braces of control statements (``if``, ``else``, ``for``,
3619 /// and ``while``) in C++ according to the LLVM coding style.
3620 /// \warning
3621 /// This option will be renamed and expanded to support other styles.
3622 /// \endwarning
3623 /// \warning
3624 /// Setting this option to ``true`` could lead to incorrect code formatting
3625 /// due to clang-format's lack of complete semantic information. As such,
3626 /// extra care should be taken to review code changes made by this option.
3627 /// \endwarning
3628 /// \code
3629 /// false: true:
3630 ///
3631 /// if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
3632 /// handleFunctionDecl(D); handleFunctionDecl(D);
3633 /// } else if (isa<VarDecl>(D)) { else if (isa<VarDecl>(D))
3634 /// handleVarDecl(D); handleVarDecl(D);
3635 /// }
3636 ///
3637 /// if (isa<VarDecl>(D)) { vs. if (isa<VarDecl>(D)) {
3638 /// for (auto *A : D.attrs()) { for (auto *A : D.attrs())
3639 /// if (shouldProcessAttr(A)) { if (shouldProcessAttr(A))
3640 /// handleAttr(A); handleAttr(A);
3641 /// } }
3642 /// }
3643 /// }
3644 ///
3645 /// if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
3646 /// for (auto *A : D.attrs()) { for (auto *A : D.attrs())
3647 /// handleAttr(A); handleAttr(A);
3648 /// }
3649 /// }
3650 ///
3651 /// if (auto *D = (T)(D)) { vs. if (auto *D = (T)(D)) {
3652 /// if (shouldProcess(D)) { if (shouldProcess(D))
3653 /// handleVarDecl(D); handleVarDecl(D);
3654 /// } else { else
3655 /// markAsIgnored(D); markAsIgnored(D);
3656 /// } }
3657 /// }
3658 ///
3659 /// if (a) { vs. if (a)
3660 /// b(); b();
3661 /// } else { else if (c)
3662 /// if (c) { d();
3663 /// d(); else
3664 /// } else { e();
3665 /// e();
3666 /// }
3667 /// }
3668 /// \endcode
3669 /// \version 14
3671
3672 /// Types of redundant parentheses to remove.
3674 /// Do not remove parentheses.
3675 /// \code
3676 /// class __declspec((dllimport)) X {};
3677 /// co_return (((0)));
3678 /// return ((a + b) - ((c + d)));
3679 /// \endcode
3681 /// Replace multiple parentheses with single parentheses.
3682 /// \code
3683 /// class __declspec(dllimport) X {};
3684 /// co_return (0);
3685 /// return ((a + b) - (c + d));
3686 /// \endcode
3688 /// Also remove parentheses enclosing the expression in a
3689 /// ``return``/``co_return`` statement.
3690 /// \code
3691 /// class __declspec(dllimport) X {};
3692 /// co_return 0;
3693 /// return (a + b) - (c + d);
3694 /// \endcode
3696 };
3697
3698 /// Remove redundant parentheses.
3699 /// \warning
3700 /// Setting this option to any value other than ``Leave`` could lead to
3701 /// incorrect code formatting due to clang-format's lack of complete semantic
3702 /// information. As such, extra care should be taken to review code changes
3703 /// made by this option.
3704 /// \endwarning
3705 /// \version 17
3707
3708 /// Remove semicolons after the closing brace of a non-empty function.
3709 /// \warning
3710 /// Setting this option to ``true`` could lead to incorrect code formatting
3711 /// due to clang-format's lack of complete semantic information. As such,
3712 /// extra care should be taken to review code changes made by this option.
3713 /// \endwarning
3714 /// \code
3715 /// false: true:
3716 ///
3717 /// int max(int a, int b) { int max(int a, int b) {
3718 /// return a > b ? a : b; return a > b ? a : b;
3719 /// }; }
3720 ///
3721 /// \endcode
3722 /// \version 16
3724
3725 /// \brief The possible positions for the requires clause. The
3726 /// ``IndentRequires`` option is only used if the ``requires`` is put on the
3727 /// start of a line.
3729 /// Always put the ``requires`` clause on its own line.
3730 /// \code
3731 /// template <typename T>
3732 /// requires C<T>
3733 /// struct Foo {...
3734 ///
3735 /// template <typename T>
3736 /// requires C<T>
3737 /// void bar(T t) {...
3738 ///
3739 /// template <typename T>
3740 /// void baz(T t)
3741 /// requires C<T>
3742 /// {...
3743 /// \endcode
3745 /// Try to put the clause together with the preceding part of a declaration.
3746 /// For class templates: stick to the template declaration.
3747 /// For function templates: stick to the template declaration.
3748 /// For function declaration followed by a requires clause: stick to the
3749 /// parameter list.
3750 /// \code
3751 /// template <typename T> requires C<T>
3752 /// struct Foo {...
3753 ///
3754 /// template <typename T> requires C<T>
3755 /// void bar(T t) {...
3756 ///
3757 /// template <typename T>
3758 /// void baz(T t) requires C<T>
3759 /// {...
3760 /// \endcode
3762 /// Try to put the ``requires`` clause together with the class or function
3763 /// declaration.
3764 /// \code
3765 /// template <typename T>
3766 /// requires C<T> struct Foo {...
3767 ///
3768 /// template <typename T>
3769 /// requires C<T> void bar(T t) {...
3770 ///
3771 /// template <typename T>
3772 /// void baz(T t)
3773 /// requires C<T> {...
3774 /// \endcode
3776 /// Try to put everything in the same line if possible. Otherwise normal
3777 /// line breaking rules take over.
3778 /// \code
3779 /// // Fitting:
3780 /// template <typename T> requires C<T> struct Foo {...
3781 ///
3782 /// template <typename T> requires C<T> void bar(T t) {...
3783 ///
3784 /// template <typename T> void bar(T t) requires C<T> {...
3785 ///
3786 /// // Not fitting, one possible example:
3787 /// template <typename LongName>
3788 /// requires C<LongName>
3789 /// struct Foo {...
3790 ///
3791 /// template <typename LongName>
3792 /// requires C<LongName>
3793 /// void bar(LongName ln) {
3794 ///
3795 /// template <typename LongName>
3796 /// void bar(LongName ln)
3797 /// requires C<LongName> {
3798 /// \endcode
3800 };
3801
3802 /// \brief The position of the ``requires`` clause.
3803 /// \version 15
3805
3806 /// Indentation logic for requires expression bodies.
3808 /// Align requires expression body relative to the indentation level of the
3809 /// outer scope the requires expression resides in.
3810 /// This is the default.
3811 /// \code
3812 /// template <typename T>
3813 /// concept C = requires(T t) {
3814 /// ...
3815 /// }
3816 /// \endcode
3818 /// Align requires expression body relative to the ``requires`` keyword.
3819 /// \code
3820 /// template <typename T>
3821 /// concept C = requires(T t) {
3822 /// ...
3823 /// }
3824 /// \endcode
3826 };
3827
3828 /// The indentation used for requires expression bodies.
3829 /// \version 16
3831
3832 /// \brief The style if definition blocks should be separated.
3834 /// Leave definition blocks as they are.
3836 /// Insert an empty line between definition blocks.
3838 /// Remove any empty line between definition blocks.
3839 SDS_Never
3841
3842 /// Specifies the use of empty lines to separate definition blocks, including
3843 /// classes, structs, enums, and functions.
3844 /// \code
3845 /// Never v.s. Always
3846 /// #include <cstring> #include <cstring>
3847 /// struct Foo {
3848 /// int a, b, c; struct Foo {
3849 /// }; int a, b, c;
3850 /// namespace Ns { };
3851 /// class Bar {
3852 /// public: namespace Ns {
3853 /// struct Foobar { class Bar {
3854 /// int a; public:
3855 /// int b; struct Foobar {
3856 /// }; int a;
3857 /// private: int b;
3858 /// int t; };
3859 /// int method1() {
3860 /// // ... private:
3861 /// } int t;
3862 /// enum List {
3863 /// ITEM1, int method1() {
3864 /// ITEM2 // ...
3865 /// }; }
3866 /// template<typename T>
3867 /// int method2(T x) { enum List {
3868 /// // ... ITEM1,
3869 /// } ITEM2
3870 /// int i, j, k; };
3871 /// int method3(int par) {
3872 /// // ... template<typename T>
3873 /// } int method2(T x) {
3874 /// }; // ...
3875 /// class C {}; }
3876 /// }
3877 /// int i, j, k;
3878 ///
3879 /// int method3(int par) {
3880 /// // ...
3881 /// }
3882 /// };
3883 ///
3884 /// class C {};
3885 /// }
3886 /// \endcode
3887 /// \version 14
3889
3890 /// The maximal number of unwrapped lines that a short namespace spans.
3891 /// Defaults to 1.
3892 ///
3893 /// This determines the maximum length of short namespaces by counting
3894 /// unwrapped lines (i.e. containing neither opening nor closing
3895 /// namespace brace) and makes "FixNamespaceComments" omit adding
3896 /// end comments for those.
3897 /// \code
3898 /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
3899 /// namespace a { namespace a {
3900 /// int foo; int foo;
3901 /// } } // namespace a
3902 ///
3903 /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
3904 /// namespace b { namespace b {
3905 /// int foo; int foo;
3906 /// int bar; int bar;
3907 /// } // namespace b } // namespace b
3908 /// \endcode
3909 /// \version 13
3911
3912 /// Include sorting options.
3913 enum SortIncludesOptions : int8_t {
3914 /// Includes are never sorted.
3915 /// \code
3916 /// #include "B/A.h"
3917 /// #include "A/B.h"
3918 /// #include "a/b.h"
3919 /// #include "A/b.h"
3920 /// #include "B/a.h"
3921 /// \endcode
3923 /// Includes are sorted in an ASCIIbetical or case sensitive fashion.
3924 /// \code
3925 /// #include "A/B.h"
3926 /// #include "A/b.h"
3927 /// #include "B/A.h"
3928 /// #include "B/a.h"
3929 /// #include "a/b.h"
3930 /// \endcode
3932 /// Includes are sorted in an alphabetical or case insensitive fashion.
3933 /// \code
3934 /// #include "A/B.h"
3935 /// #include "A/b.h"
3936 /// #include "a/b.h"
3937 /// #include "B/A.h"
3938 /// #include "B/a.h"
3939 /// \endcode
3941 };
3942
3943 /// Controls if and how clang-format will sort ``#includes``.
3944 /// \version 3.8
3946
3947 /// Position for Java Static imports.
3949 /// Static imports are placed before non-static imports.
3950 /// \code{.java}
3951 /// import static org.example.function1;
3952 ///
3953 /// import org.example.ClassA;
3954 /// \endcode
3956 /// Static imports are placed after non-static imports.
3957 /// \code{.java}
3958 /// import org.example.ClassA;
3959 ///
3960 /// import static org.example.function1;
3961 /// \endcode
3963 };
3964
3965 /// When sorting Java imports, by default static imports are placed before
3966 /// non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
3967 /// static imports are placed after non-static imports.
3968 /// \version 12
3970
3971 /// Using declaration sorting options.
3973 /// Using declarations are never sorted.
3974 /// \code
3975 /// using std::chrono::duration_cast;
3976 /// using std::move;
3977 /// using boost::regex;
3978 /// using boost::regex_constants::icase;
3979 /// using std::string;
3980 /// \endcode
3982 /// Using declarations are sorted in the order defined as follows:
3983 /// Split the strings by "::" and discard any initial empty strings. Sort
3984 /// the lists of names lexicographically, and within those groups, names are
3985 /// in case-insensitive lexicographic order.
3986 /// \code
3987 /// using boost::regex;
3988 /// using boost::regex_constants::icase;
3989 /// using std::chrono::duration_cast;
3990 /// using std::move;
3991 /// using std::string;
3992 /// \endcode
3994 /// Using declarations are sorted in the order defined as follows:
3995 /// Split the strings by "::" and discard any initial empty strings. The
3996 /// last element of each list is a non-namespace name; all others are
3997 /// namespace names. Sort the lists of names lexicographically, where the
3998 /// sort order of individual names is that all non-namespace names come
3999 /// before all namespace names, and within those groups, names are in
4000 /// case-insensitive lexicographic order.
4001 /// \code
4002 /// using boost::regex;
4003 /// using boost::regex_constants::icase;
4004 /// using std::move;
4005 /// using std::string;
4006 /// using std::chrono::duration_cast;
4007 /// \endcode
4009 };
4010
4011 /// Controls if and how clang-format will sort using declarations.
4012 /// \version 5
4014
4015 /// If ``true``, a space is inserted after C style casts.
4016 /// \code
4017 /// true: false:
4018 /// (int) i; vs. (int)i;
4019 /// \endcode
4020 /// \version 3.5
4022
4023 /// If ``true``, a space is inserted after the logical not operator (``!``).
4024 /// \code
4025 /// true: false:
4026 /// ! someExpression(); vs. !someExpression();
4027 /// \endcode
4028 /// \version 9
4030
4031 /// If \c true, a space will be inserted after the 'template' keyword.
4032 /// \code
4033 /// true: false:
4034 /// template <int> void foo(); vs. template<int> void foo();
4035 /// \endcode
4036 /// \version 4
4038
4039 /// Different ways to put a space before opening parentheses.
4041 /// Don't ensure spaces around pointer qualifiers and use PointerAlignment
4042 /// instead.
4043 /// \code
4044 /// PointerAlignment: Left PointerAlignment: Right
4045 /// void* const* x = NULL; vs. void *const *x = NULL;
4046 /// \endcode
4048 /// Ensure that there is a space before pointer qualifiers.
4049 /// \code
4050 /// PointerAlignment: Left PointerAlignment: Right
4051 /// void* const* x = NULL; vs. void * const *x = NULL;
4052 /// \endcode
4054 /// Ensure that there is a space after pointer qualifiers.
4055 /// \code
4056 /// PointerAlignment: Left PointerAlignment: Right
4057 /// void* const * x = NULL; vs. void *const *x = NULL;
4058 /// \endcode
4060 /// Ensure that there is a space both before and after pointer qualifiers.
4061 /// \code
4062 /// PointerAlignment: Left PointerAlignment: Right
4063 /// void* const * x = NULL; vs. void * const *x = NULL;
4064 /// \endcode
4066 };
4067
4068 /// Defines in which cases to put a space before or after pointer qualifiers
4069 /// \version 12
4071
4072 /// If ``false``, spaces will be removed before assignment operators.
4073 /// \code
4074 /// true: false:
4075 /// int a = 5; vs. int a= 5;
4076 /// a += 42; a+= 42;
4077 /// \endcode
4078 /// \version 3.7
4080
4081 /// If ``false``, spaces will be removed before case colon.
4082 /// \code
4083 /// true: false
4084 /// switch (x) { vs. switch (x) {
4085 /// case 1 : break; case 1: break;
4086 /// } }
4087 /// \endcode
4088 /// \version 12
4090
4091 /// If ``true``, a space will be inserted before a C++11 braced list
4092 /// used to initialize an object (after the preceding identifier or type).
4093 /// \code
4094 /// true: false:
4095 /// Foo foo { bar }; vs. Foo foo{ bar };
4096 /// Foo {}; Foo{};
4097 /// vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
4098 /// new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
4099 /// \endcode
4100 /// \version 7
4102
4103 /// If ``false``, spaces will be removed before constructor initializer
4104 /// colon.
4105 /// \code
4106 /// true: false:
4107 /// Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
4108 /// \endcode
4109 /// \version 7
4111
4112 /// If ``false``, spaces will be removed before inheritance colon.
4113 /// \code
4114 /// true: false:
4115 /// class Foo : Bar {} vs. class Foo: Bar {}
4116 /// \endcode
4117 /// \version 7
4119
4120 /// If ``true``, a space will be added before a JSON colon. For other
4121 /// languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead.
4122 /// \code
4123 /// true: false:
4124 /// { {
4125 /// "key" : "value" vs. "key": "value"
4126 /// } }
4127 /// \endcode
4128 /// \version 17
4130
4131 /// Different ways to put a space before opening parentheses.
4133 /// Never put a space before opening parentheses.
4134 /// \code
4135 /// void f() {
4136 /// if(true) {
4137 /// f();
4138 /// }
4139 /// }
4140 /// \endcode
4142 /// Put a space before opening parentheses only after control statement
4143 /// keywords (``for/if/while...``).
4144 /// \code
4145 /// void f() {
4146 /// if (true) {
4147 /// f();
4148 /// }
4149 /// }
4150 /// \endcode
4152 /// Same as ``SBPO_ControlStatements`` except this option doesn't apply to
4153 /// ForEach and If macros. This is useful in projects where ForEach/If
4154 /// macros are treated as function calls instead of control statements.
4155 /// ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
4156 /// backward compatibility.
4157 /// \code
4158 /// void f() {
4159 /// Q_FOREACH(...) {
4160 /// f();
4161 /// }
4162 /// }
4163 /// \endcode
4165 /// Put a space before opening parentheses only if the parentheses are not
4166 /// empty i.e. '()'
4167 /// \code
4168 /// void() {
4169 /// if (true) {
4170 /// f();
4171 /// g (x, y, z);
4172 /// }
4173 /// }
4174 /// \endcode
4176 /// Always put a space before opening parentheses, except when it's
4177 /// prohibited by the syntax rules (in function-like macro definitions) or
4178 /// when determined by other style rules (after unary operators, opening
4179 /// parentheses, etc.)
4180 /// \code
4181 /// void f () {
4182 /// if (true) {
4183 /// f ();
4184 /// }
4185 /// }
4186 /// \endcode
4188 /// Configure each individual space before parentheses in
4189 /// ``SpaceBeforeParensOptions``.
4191 };
4192
4193 /// Defines in which cases to put a space before opening parentheses.
4194 /// \version 3.5
4196
4197 /// Precise control over the spacing before parentheses.
4198 /// \code
4199 /// # Should be declared this way:
4200 /// SpaceBeforeParens: Custom
4201 /// SpaceBeforeParensOptions:
4202 /// AfterControlStatements: true
4203 /// AfterFunctionDefinitionName: true
4204 /// \endcode
4206 /// If ``true``, put space between control statement keywords
4207 /// (for/if/while...) and opening parentheses.
4208 /// \code
4209 /// true: false:
4210 /// if (...) {} vs. if(...) {}
4211 /// \endcode
4213 /// If ``true``, put space between foreach macros and opening parentheses.
4214 /// \code
4215 /// true: false:
4216 /// FOREACH (...) vs. FOREACH(...)
4217 /// <loop-body> <loop-body>
4218 /// \endcode
4220 /// If ``true``, put a space between function declaration name and opening
4221 /// parentheses.
4222 /// \code
4223 /// true: false:
4224 /// void f (); vs. void f();
4225 /// \endcode
4227 /// If ``true``, put a space between function definition name and opening
4228 /// parentheses.
4229 /// \code
4230 /// true: false:
4231 /// void f () {} vs. void f() {}
4232 /// \endcode
4234 /// If ``true``, put space between if macros and opening parentheses.
4235 /// \code
4236 /// true: false:
4237 /// IF (...) vs. IF(...)
4238 /// <conditional-body> <conditional-body>
4239 /// \endcode
4241 /// If ``true``, put a space between operator overloading and opening
4242 /// parentheses.
4243 /// \code
4244 /// true: false:
4245 /// void operator++ (int a); vs. void operator++(int a);
4246 /// object.operator++ (10); object.operator++(10);
4247 /// \endcode
4249 /// Styles for adding spacing between ``new/delete`` operators and opening
4250 /// parentheses.
4252 /// Remove space after ``new/delete`` operators and before ``(``.
4253 /// \code
4254 /// new(buf) T;
4255 /// delete(buf) T;
4256 /// \endcode
4258 /// Always add space after ``new/delete`` operators and before ``(``.
4259 /// \code
4260 /// new (buf) T;
4261 /// delete (buf) T;
4262 /// \endcode
4264 /// Leave placement ``new/delete`` expressions as they are.
4266 };
4267 /// Defines in which cases to put a space between ``new/delete`` operators
4268 /// and opening parentheses.
4269 /// \version 18
4271 /// If ``true``, put space between requires keyword in a requires clause and
4272 /// opening parentheses, if there is one.
4273 /// \code
4274 /// true: false:
4275 /// template<typename T> vs. template<typename T>
4276 /// requires (A<T> && B<T>) requires(A<T> && B<T>)
4277 /// ... ...
4278 /// \endcode
4280 /// If ``true``, put space between requires keyword in a requires expression
4281 /// and opening parentheses.
4282 /// \code
4283 /// true: false:
4284 /// template<typename T> vs. template<typename T>
4285 /// concept C = requires (T t) { concept C = requires(T t) {
4286 /// ... ...
4287 /// } }
4288 /// \endcode
4290 /// If ``true``, put a space before opening parentheses only if the
4291 /// parentheses are not empty.
4292 /// \code
4293 /// true: false:
4294 /// void f (int a); vs. void f();
4295 /// f (a); f();
4296 /// \endcode
4298
4306
4308 return AfterControlStatements == Other.AfterControlStatements &&
4309 AfterForeachMacros == Other.AfterForeachMacros &&
4311 Other.AfterFunctionDeclarationName &&
4312 AfterFunctionDefinitionName == Other.AfterFunctionDefinitionName &&
4313 AfterIfMacros == Other.AfterIfMacros &&
4314 AfterOverloadedOperator == Other.AfterOverloadedOperator &&
4315 AfterPlacementOperator == Other.AfterPlacementOperator &&
4316 AfterRequiresInClause == Other.AfterRequiresInClause &&
4317 AfterRequiresInExpression == Other.AfterRequiresInExpression &&
4318 BeforeNonEmptyParentheses == Other.BeforeNonEmptyParentheses;
4319 }
4320 };
4321
4322 /// Control of individual space before parentheses.
4323 ///
4324 /// If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify
4325 /// how each individual space before parentheses case should be handled.
4326 /// Otherwise, this is ignored.
4327 /// \code{.yaml}
4328 /// # Example of usage:
4329 /// SpaceBeforeParens: Custom
4330 /// SpaceBeforeParensOptions:
4331 /// AfterControlStatements: true
4332 /// AfterFunctionDefinitionName: true
4333 /// \endcode
4334 /// \version 14
4336
4337 /// If ``true``, spaces will be before ``[``.
4338 /// Lambdas will not be affected. Only the first ``[`` will get a space added.
4339 /// \code
4340 /// true: false:
4341 /// int a [5]; vs. int a[5];
4342 /// int a [5][5]; vs. int a[5][5];
4343 /// \endcode
4344 /// \version 10
4346
4347 /// If ``false``, spaces will be removed before range-based for loop
4348 /// colon.
4349 /// \code
4350 /// true: false:
4351 /// for (auto v : values) {} vs. for(auto v: values) {}
4352 /// \endcode
4353 /// \version 7
4355
4356 /// If ``true``, spaces will be inserted into ``{}``.
4357 /// \code
4358 /// true: false:
4359 /// void f() { } vs. void f() {}
4360 /// while (true) { } while (true) {}
4361 /// \endcode
4362 /// \version 10
4364
4365 /// If ``true``, spaces may be inserted into ``()``.
4366 /// This option is **deprecated**. See ``InEmptyParentheses`` of
4367 /// ``SpacesInParensOptions``.
4368 /// \version 3.7
4369 // bool SpaceInEmptyParentheses;
4370
4371 /// The number of spaces before trailing line comments
4372 /// (``//`` - comments).
4373 ///
4374 /// This does not affect trailing block comments (``/*`` - comments) as those
4375 /// commonly have different usage patterns and a number of special cases. In
4376 /// the case of Verilog, it doesn't affect a comment right after the opening
4377 /// parenthesis in the port or parameter list in a module header, because it
4378 /// is probably for the port on the following line instead of the parenthesis
4379 /// it follows.
4380 /// \code
4381 /// SpacesBeforeTrailingComments: 3
4382 /// void f() {
4383 /// if (true) { // foo1
4384 /// f(); // bar
4385 /// } // foo
4386 /// }
4387 /// \endcode
4388 /// \version 3.7
4390
4391 /// Styles for adding spacing after ``<`` and before ``>``
4392 /// in template argument lists.
4393 enum SpacesInAnglesStyle : int8_t {
4394 /// Remove spaces after ``<`` and before ``>``.
4395 /// \code
4396 /// static_cast<int>(arg);
4397 /// std::function<void(int)> fct;
4398 /// \endcode
4400 /// Add spaces after ``<`` and before ``>``.
4401 /// \code
4402 /// static_cast< int >(arg);
4403 /// std::function< void(int) > fct;
4404 /// \endcode
4406 /// Keep a single space after ``<`` and before ``>`` if any spaces were
4407 /// present. Option ``Standard: Cpp03`` takes precedence.
4410 /// The SpacesInAnglesStyle to use for template argument lists.
4411 /// \version 3.4
4413
4414 /// If ``true``, spaces will be inserted around if/for/switch/while
4415 /// conditions.
4416 /// This option is **deprecated**. See ``InConditionalStatements`` of
4417 /// ``SpacesInParensOptions``.
4418 /// \version 10
4419 // bool SpacesInConditionalStatement;
4420
4421 /// If ``true``, spaces are inserted inside container literals (e.g. ObjC and
4422 /// Javascript array and dict literals). For JSON, use
4423 /// ``SpaceBeforeJsonColon`` instead.
4424 /// \code{.js}
4425 /// true: false:
4426 /// var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
4427 /// f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
4428 /// \endcode
4429 /// \version 3.7
4431
4432 /// If ``true``, spaces may be inserted into C style casts.
4433 /// This option is **deprecated**. See ``InCStyleCasts`` of
4434 /// ``SpacesInParensOptions``.
4435 /// \version 3.7
4436 // bool SpacesInCStyleCastParentheses;
4437
4438 /// Control of spaces within a single line comment.
4440 /// The minimum number of spaces at the start of the comment.
4441 unsigned Minimum;
4442 /// The maximum number of spaces at the start of the comment.
4443 unsigned Maximum;
4444 };
4445
4446 /// How many spaces are allowed at the start of a line comment. To disable the
4447 /// maximum set it to ``-1``, apart from that the maximum takes precedence
4448 /// over the minimum.
4449 /// \code
4450 /// Minimum = 1
4451 /// Maximum = -1
4452 /// // One space is forced
4453 ///
4454 /// // but more spaces are possible
4455 ///
4456 /// Minimum = 0
4457 /// Maximum = 0
4458 /// //Forces to start every comment directly after the slashes
4459 /// \endcode
4460 ///
4461 /// Note that in line comment sections the relative indent of the subsequent
4462 /// lines is kept, that means the following:
4463 /// \code
4464 /// before: after:
4465 /// Minimum: 1
4466 /// //if (b) { // if (b) {
4467 /// // return true; // return true;
4468 /// //} // }
4469 ///
4470 /// Maximum: 0
4471 /// /// List: ///List:
4472 /// /// - Foo /// - Foo
4473 /// /// - Bar /// - Bar
4474 /// \endcode
4475 ///
4476 /// This option has only effect if ``ReflowComments`` is set to ``true``.
4477 /// \version 13
4479
4480 /// Different ways to put a space before opening and closing parentheses.
4481 enum SpacesInParensStyle : int8_t {
4482 /// Never put a space in parentheses.
4483 /// \code
4484 /// void f() {
4485 /// if(true) {
4486 /// f();
4487 /// }
4488 /// }
4489 /// \endcode
4491 /// Configure each individual space in parentheses in
4492 /// `SpacesInParensOptions`.
4494 };
4495
4496 /// If ``true``, spaces will be inserted after ``(`` and before ``)``.
4497 /// This option is **deprecated**. The previous behavior is preserved by using
4498 /// ``SpacesInParens`` with ``Custom`` and by setting all
4499 /// ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and
4500 /// ``InEmptyParentheses``.
4501 /// \version 3.7
4502 // bool SpacesInParentheses;
4503
4504 /// Defines in which cases spaces will be inserted after ``(`` and before
4505 /// ``)``.
4506 /// \version 17
4508
4509 /// Precise control over the spacing in parentheses.
4510 /// \code
4511 /// # Should be declared this way:
4512 /// SpacesInParens: Custom
4513 /// SpacesInParensOptions:
4514 /// InConditionalStatements: true
4515 /// Other: true
4516 /// \endcode
4518 /// Put a space in parentheses only inside conditional statements
4519 /// (``for/if/while/switch...``).
4520 /// \code
4521 /// true: false:
4522 /// if ( a ) { ... } vs. if (a) { ... }
4523 /// while ( i < 5 ) { ... } while (i < 5) { ... }
4524 /// \endcode
4526 /// Put a space in C style casts.
4527 /// \code
4528 /// true: false:
4529 /// x = ( int32 )y vs. x = (int32)y
4530 /// \endcode
4532 /// Put a space in parentheses only if the parentheses are empty i.e. '()'
4533 /// \code
4534 /// true: false:
4535 /// void f( ) { vs. void f() {
4536 /// int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
4537 /// if (true) { if (true) {
4538 /// f( ); f();
4539 /// } }
4540 /// } }
4541 /// \endcode
4543 /// Put a space in parentheses not covered by preceding options.
4544 /// \code
4545 /// true: false:
4546 /// t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
4547 /// \endcode
4548 bool Other;
4549
4553
4555 bool InEmptyParentheses, bool Other)
4558 Other(Other) {}
4559
4560 bool operator==(const SpacesInParensCustom &R) const {
4564 }
4565 bool operator!=(const SpacesInParensCustom &R) const {
4566 return !(*this == R);
4567 }
4568 };
4569
4570 /// Control of individual spaces in parentheses.
4571 ///
4572 /// If ``SpacesInParens`` is set to ``Custom``, use this to specify
4573 /// how each individual space in parentheses case should be handled.
4574 /// Otherwise, this is ignored.
4575 /// \code{.yaml}
4576 /// # Example of usage:
4577 /// SpacesInParens: Custom
4578 /// SpacesInParensOptions:
4579 /// InConditionalStatements: true
4580 /// InEmptyParentheses: true
4581 /// \endcode
4582 /// \version 17
4584
4585 /// If ``true``, spaces will be inserted after ``[`` and before ``]``.
4586 /// Lambdas without arguments or unspecified size array declarations will not
4587 /// be affected.
4588 /// \code
4589 /// true: false:
4590 /// int a[ 5 ]; vs. int a[5];
4591 /// std::unique_ptr<int[]> foo() {} // Won't be affected
4592 /// \endcode
4593 /// \version 3.7
4595
4596 /// Supported language standards for parsing and formatting C++ constructs.
4597 /// \code
4598 /// Latest: vector<set<int>>
4599 /// c++03 vs. vector<set<int> >
4600 /// \endcode
4601 ///
4602 /// The correct way to spell a specific language version is e.g. ``c++11``.
4603 /// The historical aliases ``Cpp03`` and ``Cpp11`` are deprecated.
4604 enum LanguageStandard : int8_t {
4605 /// Parse and format as C++03.
4606 /// ``Cpp03`` is a deprecated alias for ``c++03``
4607 LS_Cpp03, // c++03
4608 /// Parse and format as C++11.
4609 LS_Cpp11, // c++11
4610 /// Parse and format as C++14.
4611 LS_Cpp14, // c++14
4612 /// Parse and format as C++17.
4613 LS_Cpp17, // c++17
4614 /// Parse and format as C++20.
4615 LS_Cpp20, // c++20
4616 /// Parse and format using the latest supported language version.
4617 /// ``Cpp11`` is a deprecated alias for ``Latest``
4619 /// Automatic detection based on the input.
4621 };
4622
4623 /// Parse and format C++ constructs compatible with this standard.
4624 /// \code
4625 /// c++03: latest:
4626 /// vector<set<int> > x; vs. vector<set<int>> x;
4627 /// \endcode
4628 /// \version 3.7
4630
4631 /// Macros which are ignored in front of a statement, as if they were an
4632 /// attribute. So that they are not parsed as identifier, for example for Qts
4633 /// emit.
4634 /// \code
4635 /// AlignConsecutiveDeclarations: true
4636 /// StatementAttributeLikeMacros: []
4637 /// unsigned char data = 'x';
4638 /// emit signal(data); // This is parsed as variable declaration.
4639 ///
4640 /// AlignConsecutiveDeclarations: true
4641 /// StatementAttributeLikeMacros: [emit]
4642 /// unsigned char data = 'x';
4643 /// emit signal(data); // Now it's fine again.
4644 /// \endcode
4645 /// \version 12
4646 std::vector<std::string> StatementAttributeLikeMacros;
4647
4648 /// A vector of macros that should be interpreted as complete
4649 /// statements.
4650 ///
4651 /// Typical macros are expressions, and require a semi-colon to be
4652 /// added; sometimes this is not the case, and this allows to make
4653 /// clang-format aware of such cases.
4654 ///
4655 /// For example: Q_UNUSED
4656 /// \version 8
4657 std::vector<std::string> StatementMacros;
4658
4659 /// The number of columns used for tab stops.
4660 /// \version 3.7
4661 unsigned TabWidth;
4662
4663 /// A vector of non-keyword identifiers that should be interpreted as type
4664 /// names.
4665 ///
4666 /// A ``*``, ``&``, or ``&&`` between a type name and another non-keyword
4667 /// identifier is annotated as a pointer or reference token instead of a
4668 /// binary operator.
4669 ///
4670 /// \version 17
4671 std::vector<std::string> TypeNames;
4672
4673 /// \brief A vector of macros that should be interpreted as type declarations
4674 /// instead of as function calls.
4675 ///
4676 /// These are expected to be macros of the form:
4677 /// \code
4678 /// STACK_OF(...)
4679 /// \endcode
4680 ///
4681 /// In the .clang-format configuration file, this can be configured like:
4682 /// \code{.yaml}
4683 /// TypenameMacros: ['STACK_OF', 'LIST']
4684 /// \endcode
4685 ///
4686 /// For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
4687 /// \version 9
4688 std::vector<std::string> TypenameMacros;
4689
4690 /// This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``.
4691 /// \version 10
4692 // bool UseCRLF;
4693
4694 /// Different ways to use tab in formatting.
4695 enum UseTabStyle : int8_t {
4696 /// Never use tab.
4698 /// Use tabs only for indentation.
4700 /// Fill all leading whitespace with tabs, and use spaces for alignment that
4701 /// appears within a line (e.g. consecutive assignments and declarations).
4703 /// Use tabs for line continuation and indentation, and spaces for
4704 /// alignment.
4706 /// Use tabs whenever we need to fill whitespace that spans at least from
4707 /// one tab stop to the next one.
4708 UT_Always
4710
4711 /// The way to use tab characters in the resulting file.
4712 /// \version 3.7
4714
4715 /// For Verilog, put each port on its own line in module instantiations.
4716 /// \code
4717 /// true:
4718 /// ffnand ff1(.q(),
4719 /// .qbar(out1),
4720 /// .clear(in1),
4721 /// .preset(in2));
4722 ///
4723 /// false:
4724 /// ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2));
4725 /// \endcode
4726 /// \version 17
4728
4729 /// A vector of macros which are whitespace-sensitive and should not
4730 /// be touched.
4731 ///
4732 /// These are expected to be macros of the form:
4733 /// \code
4734 /// STRINGIZE(...)
4735 /// \endcode
4736 ///
4737 /// In the .clang-format configuration file, this can be configured like:
4738 /// \code{.yaml}
4739 /// WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE']
4740 /// \endcode
4741 ///
4742 /// For example: BOOST_PP_STRINGIZE
4743 /// \version 11
4744 std::vector<std::string> WhitespaceSensitiveMacros;
4745
4746 bool operator==(const FormatStyle &R) const {
4789 BreakArrays == R.BreakArrays &&
4825 IndentWidth == R.IndentWidth &&
4836 Language == R.Language &&
4903 Standard == R.Standard &&
4907 UseTab == R.UseTab &&
4911 }
4912
4913 std::optional<FormatStyle> GetLanguageStyle(LanguageKind Language) const;
4914
4915 // Stores per-language styles. A FormatStyle instance inside has an empty
4916 // StyleSet. A FormatStyle instance returned by the Get method has its
4917 // StyleSet set to a copy of the originating StyleSet, effectively keeping the
4918 // internal representation of that StyleSet alive.
4919 //
4920 // The memory management and ownership reminds of a birds nest: chicks
4921 // leaving the nest take photos of the nest with them.
4923 typedef std::map<FormatStyle::LanguageKind, FormatStyle> MapType;
4924
4925 std::optional<FormatStyle> Get(FormatStyle::LanguageKind Language) const;
4926
4927 // Adds \p Style to this FormatStyleSet. Style must not have an associated
4928 // FormatStyleSet.
4929 // Style.Language should be different than LK_None. If this FormatStyleSet
4930 // already contains an entry for Style.Language, that gets replaced with the
4931 // passed Style.
4932 void Add(FormatStyle Style);
4933
4934 // Clears this FormatStyleSet.
4935 void Clear();
4936
4937 private:
4938 std::shared_ptr<MapType> Styles;
4939 };
4940
4942 const FormatStyle &MainStyle,
4943 const std::vector<FormatStyle> &ConfigurationStyles);
4944
4945private:
4946 FormatStyleSet StyleSet;
4947
4948 friend std::error_code
4949 parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style,
4950 bool AllowUnknownOptions,
4951 llvm::SourceMgr::DiagHandlerTy DiagHandler,
4952 void *DiagHandlerCtxt);
4953};
4954
4955/// Returns a format style complying with the LLVM coding standards:
4956/// http://llvm.org/docs/CodingStandards.html.
4959
4960/// Returns a format style complying with one of Google's style guides:
4961/// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
4962/// http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml.
4963/// https://developers.google.com/protocol-buffers/docs/style.
4965
4966/// Returns a format style complying with Chromium's style guide:
4967/// http://www.chromium.org/developers/coding-style.
4969
4970/// Returns a format style complying with Mozilla's style guide:
4971/// https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html.
4973
4974/// Returns a format style complying with Webkit's style guide:
4975/// http://www.webkit.org/coding/coding-style.html
4977
4978/// Returns a format style complying with GNU Coding Standards:
4979/// http://www.gnu.org/prep/standards/standards.html
4981
4982/// Returns a format style complying with Microsoft style guide:
4983/// https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017
4985
4987
4988/// Returns style indicating formatting should be not applied at all.
4990
4991/// Gets a predefined style for the specified language by name.
4992///
4993/// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
4994/// compared case-insensitively.
4995///
4996/// Returns ``true`` if the Style has been set.
4998 FormatStyle *Style);
4999
5000/// Parse configuration from YAML-formatted text.
5001///
5002/// Style->Language is used to get the base style, if the ``BasedOnStyle``
5003/// option is present.
5004///
5005/// The FormatStyleSet of Style is reset.
5006///
5007/// When ``BasedOnStyle`` is not present, options not present in the YAML
5008/// document, are retained in \p Style.
5009///
5010/// If AllowUnknownOptions is true, no errors are emitted if unknown
5011/// format options are occurred.
5012///
5013/// If set all diagnostics are emitted through the DiagHandler.
5014std::error_code
5015parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style,
5016 bool AllowUnknownOptions = false,
5017 llvm::SourceMgr::DiagHandlerTy DiagHandler = nullptr,
5018 void *DiagHandlerCtx = nullptr);
5019
5020/// Like above but accepts an unnamed buffer.
5021inline std::error_code parseConfiguration(StringRef Config, FormatStyle *Style,
5022 bool AllowUnknownOptions = false) {
5023 return parseConfiguration(llvm::MemoryBufferRef(Config, "YAML"), Style,
5024 AllowUnknownOptions);
5025}
5026
5027/// Gets configuration in a YAML string.
5028std::string configurationAsText(const FormatStyle &Style);
5029
5030/// Returns the replacements necessary to sort all ``#include`` blocks
5031/// that are affected by ``Ranges``.
5032tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
5034 StringRef FileName,
5035 unsigned *Cursor = nullptr);
5036
5037/// Returns the replacements corresponding to applying and formatting
5038/// \p Replaces on success; otheriwse, return an llvm::Error carrying
5039/// llvm::StringError.
5041formatReplacements(StringRef Code, const tooling::Replacements &Replaces,
5042 const FormatStyle &Style);
5043
5044/// Returns the replacements corresponding to applying \p Replaces and
5045/// cleaning up the code after that on success; otherwise, return an llvm::Error
5046/// carrying llvm::StringError.
5047/// This also supports inserting/deleting C++ #include directives:
5048/// - If a replacement has offset UINT_MAX, length 0, and a replacement text
5049/// that is an #include directive, this will insert the #include into the
5050/// correct block in the \p Code.
5051/// - If a replacement has offset UINT_MAX, length 1, and a replacement text
5052/// that is the name of the header to be removed, the header will be removed
5053/// from \p Code if it exists.
5054/// The include manipulation is done via ``tooling::HeaderInclude``, see its
5055/// documentation for more details on how include insertion points are found and
5056/// what edits are produced.
5058cleanupAroundReplacements(StringRef Code, const tooling::Replacements &Replaces,
5059 const FormatStyle &Style);
5060
5061/// Represents the status of a formatting attempt.
5063 /// A value of ``false`` means that any of the affected ranges were not
5064 /// formatted due to a non-recoverable syntax error.
5065 bool FormatComplete = true;
5066
5067 /// If ``FormatComplete`` is false, ``Line`` records a one-based
5068 /// original line number at which a syntax error might have occurred. This is
5069 /// based on a best-effort analysis and could be imprecise.
5070 unsigned Line = 0;
5071};
5072
5073/// Reformats the given \p Ranges in \p Code.
5074///
5075/// Each range is extended on either end to its next bigger logic unit, i.e.
5076/// everything that might influence its formatting or might be influenced by its
5077/// formatting.
5078///
5079/// Returns the ``Replacements`` necessary to make all \p Ranges comply with
5080/// \p Style.
5081///
5082/// If ``Status`` is non-null, its value will be populated with the status of
5083/// this formatting attempt. See \c FormattingAttemptStatus.
5084tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
5086 StringRef FileName = "<stdin>",
5087 FormattingAttemptStatus *Status = nullptr);
5088
5089/// Same as above, except if ``IncompleteFormat`` is non-null, its value
5090/// will be set to true if any of the affected ranges were not formatted due to
5091/// a non-recoverable syntax error.
5092tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
5094 StringRef FileName, bool *IncompleteFormat);
5095
5096/// Clean up any erroneous/redundant code in the given \p Ranges in \p
5097/// Code.
5098///
5099/// Returns the ``Replacements`` that clean up all \p Ranges in \p Code.
5100tooling::Replacements cleanup(const FormatStyle &Style, StringRef Code,
5102 StringRef FileName = "<stdin>");
5103
5104/// Fix namespace end comments in the given \p Ranges in \p Code.
5105///
5106/// Returns the ``Replacements`` that fix the namespace comments in all
5107/// \p Ranges in \p Code.
5109 StringRef Code,
5111 StringRef FileName = "<stdin>");
5112
5113/// Inserts or removes empty lines separating definition blocks including
5114/// classes, structs, functions, namespaces, and enums in the given \p Ranges in
5115/// \p Code.
5116///
5117/// Returns the ``Replacements`` that inserts or removes empty lines separating
5118/// definition blocks in all \p Ranges in \p Code.
5120 StringRef Code,
5122 StringRef FileName = "<stdin>");
5123
5124/// Sort consecutive using declarations in the given \p Ranges in
5125/// \p Code.
5126///
5127/// Returns the ``Replacements`` that sort the using declarations in all
5128/// \p Ranges in \p Code.
5130 StringRef Code,
5132 StringRef FileName = "<stdin>");
5133
5134/// Returns the ``LangOpts`` that the formatter expects you to set.
5135///
5136/// \param Style determines specific settings for lexing mode.
5138
5139/// Description to be used for help text for a ``llvm::cl`` option for
5140/// specifying format style. The description is closely related to the operation
5141/// of ``getStyle()``.
5142extern const char *StyleOptionHelpDescription;
5143
5144/// The suggested format style to use by default. This allows tools using
5145/// ``getStyle`` to have a consistent default style.
5146/// Different builds can modify the value to the preferred styles.
5147extern const char *DefaultFormatStyle;
5148
5149/// The suggested predefined style to use as the fallback style in ``getStyle``.
5150/// Different builds can modify the value to the preferred styles.
5151extern const char *DefaultFallbackStyle;
5152
5153/// Construct a FormatStyle based on ``StyleName``.
5154///
5155/// ``StyleName`` can take several forms:
5156/// * "{<key>: <value>, ...}" - Set specic style parameters.
5157/// * "<style name>" - One of the style names supported by
5158/// getPredefinedStyle().
5159/// * "file" - Load style configuration from a file called ``.clang-format``
5160/// located in one of the parent directories of ``FileName`` or the current
5161/// directory if ``FileName`` is empty.
5162/// * "file:<format_file_path>" to explicitly specify the configuration file to
5163/// use.
5164///
5165/// \param[in] StyleName Style name to interpret according to the description
5166/// above.
5167/// \param[in] FileName Path to start search for .clang-format if ``StyleName``
5168/// == "file".
5169/// \param[in] FallbackStyle The name of a predefined style used to fallback to
5170/// in case \p StyleName is "file" and no file can be found.
5171/// \param[in] Code The actual code to be formatted. Used to determine the
5172/// language if the filename isn't sufficient.
5173/// \param[in] FS The underlying file system, in which the file resides. By
5174/// default, the file system is the real file system.
5175/// \param[in] AllowUnknownOptions If true, unknown format options only
5176/// emit a warning. If false, errors are emitted on unknown format
5177/// options.
5178///
5179/// \returns FormatStyle as specified by ``StyleName``. If ``StyleName`` is
5180/// "file" and no file is found, returns ``FallbackStyle``. If no style could be
5181/// determined, returns an Error.
5182llvm::Expected<FormatStyle> getStyle(StringRef StyleName, StringRef FileName,
5183 StringRef FallbackStyle,
5184 StringRef Code = "",
5185 llvm::vfs::FileSystem *FS = nullptr,
5186 bool AllowUnknownOptions = false);
5187
5188// Guesses the language from the ``FileName`` and ``Code`` to be formatted.
5189// Defaults to FormatStyle::LK_Cpp.
5190FormatStyle::LanguageKind guessLanguage(StringRef FileName, StringRef Code);
5191
5192// Returns a string representation of ``Language``.
5194 switch (Language) {
5196 return "C++";
5198 return "CSharp";
5200 return "Objective-C";
5202 return "Java";
5204 return "JavaScript";
5206 return "Json";
5208 return "Proto";
5210 return "TableGen";
5212 return "TextProto";
5214 return "Verilog";
5215 default:
5216 return "Unknown";
5217 }
5218}
5219
5220bool isClangFormatOn(StringRef Comment);
5221bool isClangFormatOff(StringRef Comment);
5222
5223} // end namespace format
5224} // end namespace clang
5225
5226namespace std {
5227template <>
5228struct is_error_code_enum<clang::format::ParseError> : std::true_type {};
5229} // namespace std
5230
5231#endif // LLVM_CLANG_FORMAT_FORMAT_H
Defines the clang::LangOptions interface.
Keeps track of the various options that can be enabled, which controls the dialect of C or C++ that i...
Definition: LangOptions.h:83
const char * name() const noexcept override
Definition: Format.cpp:1258
std::string message(int EV) const override
Definition: Format.cpp:1262
Maintains a set of replacements that are conflict-free.
Definition: Replacement.h:212
const char * StyleOptionHelpDescription
Description to be used for help text for a llvm::cl option for specifying format style.
Definition: Format.cpp:3869
const char * DefaultFallbackStyle
The suggested predefined style to use as the fallback style in getStyle.
Definition: Format.cpp:3940
FormatStyle getWebKitStyle()
Returns a format style complying with Webkit's style guide: http://www.webkit.org/coding/coding-style...
Definition: Format.cpp:1858
llvm::Expected< tooling::Replacements > cleanupAroundReplacements(StringRef Code, const tooling::Replacements &Replaces, const FormatStyle &Style)
Returns the replacements corresponding to applying Replaces and cleaning up the code after that on su...
Definition: Format.cpp:3583
std::error_code make_error_code(ParseError e)
Definition: Format.cpp:1249
FormatStyle getClangFormatStyle()
Definition: Format.cpp:1927
FormatStyle getLLVMStyle(FormatStyle::LanguageKind Language=FormatStyle::LanguageKind::LK_Cpp)
Returns a format style complying with the LLVM coding standards: http://llvm.org/docs/CodingStandards...
Definition: Format.cpp:1425
FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language)
Returns a format style complying with one of Google's style guides: http://google-styleguide....
Definition: Format.cpp:1631
std::string configurationAsText(const FormatStyle &Style)
Gets configuration in a YAML string.
Definition: Format.cpp:2072
FormatStyle getMicrosoftStyle(FormatStyle::LanguageKind Language)
Returns a format style complying with Microsoft style guide: https://docs.microsoft....
Definition: Format.cpp:1897
std::error_code parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style, bool AllowUnknownOptions=false, llvm::SourceMgr::DiagHandlerTy DiagHandler=nullptr, void *DiagHandlerCtx=nullptr)
Parse configuration from YAML-formatted text.
Definition: Format.cpp:2006
const std::error_category & getParseCategory()
Definition: Format.cpp:1245
tooling::Replacements fixNamespaceEndComments(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName="<stdin>")
Fix namespace end comments in the given Ranges in Code.
Definition: Format.cpp:3819
FormatStyle::LanguageKind guessLanguage(StringRef FileName, StringRef Code)
Definition: Format.cpp:3919
const char * DefaultFormatStyle
The suggested format style to use by default.
Definition: Format.cpp:3938
llvm::Expected< FormatStyle > getStyle(StringRef StyleName, StringRef FileName, StringRef FallbackStyle, StringRef Code="", llvm::vfs::FileSystem *FS=nullptr, bool AllowUnknownOptions=false)
Construct a FormatStyle based on StyleName.
Definition: Format.cpp:3954
FormatStyle getGNUStyle()
Returns a format style complying with GNU Coding Standards: http://www.gnu.org/prep/standards/standar...
Definition: Format.cpp:1882
bool isClangFormatOff(StringRef Comment)
Definition: Format.cpp:4133
LangOptions getFormattingLangOpts(const FormatStyle &Style=getLLVMStyle())
Returns the LangOpts that the formatter expects you to set.
Definition: Format.cpp:3839
FormatStyle getMozillaStyle()
Returns a format style complying with Mozilla's style guide: https://firefox-source-docs....
Definition: Format.cpp:1832
bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language, FormatStyle *Style)
Gets a predefined style for the specified language by name.
Definition: Format.cpp:1945
tooling::Replacements reformat(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName="<stdin>", FormattingAttemptStatus *Status=nullptr)
Reformats the given Ranges in Code.
Definition: Format.cpp:3786
bool isClangFormatOn(StringRef Comment)
Definition: Format.cpp:4129
tooling::Replacements sortUsingDeclarations(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName="<stdin>")
Sort consecutive using declarations in the given Ranges in Code.
Definition: Format.cpp:3829
FormatStyle getChromiumStyle(FormatStyle::LanguageKind Language)
Returns a format style complying with Chromium's style guide: http://www.chromium....
Definition: Format.cpp:1772
tooling::Replacements cleanup(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName="<stdin>")
Clean up any erroneous/redundant code in the given Ranges in Code.
Definition: Format.cpp:3797
FormatStyle getNoStyle()
Returns style indicating formatting should be not applied at all.
Definition: Format.cpp:1937
tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName, unsigned *Cursor=nullptr)
Returns the replacements necessary to sort all #include blocks that are affected by Ranges.
Definition: Format.cpp:3431
tooling::Replacements separateDefinitionBlocks(const FormatStyle &Style, StringRef Code, ArrayRef< tooling::Range > Ranges, StringRef FileName="<stdin>")
Inserts or removes empty lines separating definition blocks including classes, structs,...
llvm::Expected< tooling::Replacements > formatReplacements(StringRef Code, const tooling::Replacements &Replaces, const FormatStyle &Style)
Returns the replacements corresponding to applying and formatting Replaces on success; otheriwse,...
Definition: Format.cpp:3472
StringRef getLanguageName(FormatStyle::LanguageKind Language)
Definition: Format.h:5193
Language
The language for the input, used to select and validate the language standard and possible actions.
Definition: LangStandard.h:23
YAML serialization mapping.
Definition: Dominators.h:30
Definition: Format.h:5226
#define false
Definition: stdbool.h:22
bool AcrossEmptyLines
Whether to align across empty lines.
Definition: Format.h:202
bool PadOperators
Only for AlignConsecutiveAssignments.
Definition: Format.h:246
bool operator!=(const AlignConsecutiveStyle &R) const
Definition: Format.h:252
bool operator==(const AlignConsecutiveStyle &R) const
Definition: Format.h:247
bool Enabled
Whether aligning is enabled.
Definition: Format.h:185
bool AlignCompound
Only for AlignConsecutiveAssignments.
Definition: Format.h:227
bool AcrossComments
Whether to align across comments.
Definition: Format.h:215
Precise control over the wrapping of braces.
Definition: Format.h:1187
bool SplitEmptyRecord
If false, empty record (e.g.
Definition: Format.h:1397
bool AfterClass
Wrap class definitions.
Definition: Format.h:1213
bool AfterStruct
Wrap struct definitions.
Definition: Format.h:1280
bool AfterUnion
Wrap union definitions.
Definition: Format.h:1294
bool AfterEnum
Wrap enum definitions.
Definition: Format.h:1228
bool IndentBraces
Indent the wrapped braces themselves.
Definition: Format.h:1371
bool AfterObjCDeclaration
Wrap ObjC definitions (interfaces, implementations...).
Definition: Format.h:1266
bool AfterNamespace
Wrap namespace definitions.
Definition: Format.h:1260
bool SplitEmptyNamespace
If false, empty namespace body can be put on a single line.
Definition: Format.h:1409
BraceWrappingAfterControlStatementStyle AfterControlStatement
Wrap control statements (if/for/while/switch/..).
Definition: Format.h:1216
bool AfterFunction
Wrap function definitions.
Definition: Format.h:1244
bool SplitEmptyFunction
If false, empty function body can be put on a single line.
Definition: Format.h:1385
bool AfterExternBlock
Wrap extern blocks.
Definition: Format.h:1308
std::map< FormatStyle::LanguageKind, FormatStyle > MapType
Definition: Format.h:4923
std::optional< FormatStyle > Get(FormatStyle::LanguageKind Language) const
Definition: Format.cpp:2088
Separator format of integer literals of different bases.
Definition: Format.h:2812
int8_t BinaryMinDigits
Format separators in binary literals with a minimum number of digits.
Definition: Format.h:2828
bool operator==(const IntegerLiteralSeparatorStyle &R) const
Definition: Format.h:2860
int8_t Binary
Format separators in binary literals.
Definition: Format.h:2820
int8_t DecimalMinDigits
Format separators in decimal literals with a minimum number of digits.
Definition: Format.h:2843
int8_t Decimal
Format separators in decimal literals.
Definition: Format.h:2835