diff options
Diffstat (limited to 'contrib/llvm-project/clang/include/clang/Format/Format.h')
| -rwxr-xr-x | contrib/llvm-project/clang/include/clang/Format/Format.h | 3614 |
1 files changed, 2703 insertions, 911 deletions
diff --git a/contrib/llvm-project/clang/include/clang/Format/Format.h b/contrib/llvm-project/clang/include/clang/Format/Format.h index 96c2a74e97db..efcb4e1d87ea 100755 --- a/contrib/llvm-project/clang/include/clang/Format/Format.h +++ b/contrib/llvm-project/clang/include/clang/Format/Format.h @@ -19,6 +19,8 @@ #include "clang/Tooling/Inclusions/IncludeStyle.h" #include "llvm/ADT/ArrayRef.h" #include "llvm/Support/Regex.h" +#include "llvm/Support/SourceMgr.h" +#include <optional> #include <system_error> namespace llvm { @@ -28,18 +30,17 @@ class FileSystem; } // namespace llvm namespace clang { - -class Lexer; -class SourceManager; -class DiagnosticConsumer; - namespace format { enum class ParseError { Success = 0, Error, Unsuitable, - BinPackTrailingCommaConflict + BinPackTrailingCommaConflict, + InvalidQualifierSpecified, + DuplicateQualifierSpecified, + MissingQualifierType, + MissingQualifierOrder }; class ParseErrorCategory final : public std::error_category { public: @@ -52,11 +53,17 @@ std::error_code make_error_code(ParseError e); /// The ``FormatStyle`` is used to configure the formatting to follow /// specific guidelines. struct FormatStyle { + // If the BasedOn: was InheritParentConfig and this style needs the file from + // the parent directories. It is not part of the actual style for formatting. + // Thus the // instead of ///. + bool InheritsParentConfig; + /// The extra indent or outdent of access modifiers, e.g. ``public:``. + /// \version 3.3 int AccessModifierOffset; /// Different styles for aligning after open brackets. - enum BracketAlignmentStyle : unsigned char { + enum BracketAlignmentStyle : int8_t { /// Align parameters on the open bracket, e.g.: /// \code /// someLongFunction(argument1, @@ -76,26 +83,193 @@ struct FormatStyle { /// argument1, argument2); /// \endcode BAS_AlwaysBreak, + /// Always break after an open bracket, if the parameters don't fit + /// on a single line. Closing brackets will be placed on a new line. + /// E.g.: + /// \code + /// someLongFunction( + /// argument1, argument2 + /// ) + /// \endcode + /// + /// \note + /// This currently only applies to braced initializer lists (when + /// ``Cpp11BracedListStyle`` is ``true``) and parentheses. + /// \endnote + BAS_BlockIndent, }; /// If ``true``, horizontally aligns arguments after an open bracket. /// /// This applies to round brackets (parentheses), angle brackets and square /// brackets. + /// \version 3.8 BracketAlignmentStyle AlignAfterOpenBracket; - /// Styles for alignment of consecutive tokens. Tokens can be assignment signs - /// (see - /// ``AlignConsecutiveAssignments``), bitfield member separators (see - /// ``AlignConsecutiveBitFields``), names in declarations (see - /// ``AlignConsecutiveDeclarations``) or macro definitions (see - /// ``AlignConsecutiveMacros``). - enum AlignConsecutiveStyle { - ACS_None, - ACS_Consecutive, - ACS_AcrossEmptyLines, - ACS_AcrossComments, - ACS_AcrossEmptyLinesAndComments + /// Different style for aligning array initializers. + enum ArrayInitializerAlignmentStyle : int8_t { + /// Align array column and left justify the columns e.g.: + /// \code + /// struct test demo[] = + /// { + /// {56, 23, "hello"}, + /// {-1, 93463, "world"}, + /// {7, 5, "!!" } + /// }; + /// \endcode + AIAS_Left, + /// Align array column and right justify the columns e.g.: + /// \code + /// struct test demo[] = + /// { + /// {56, 23, "hello"}, + /// {-1, 93463, "world"}, + /// { 7, 5, "!!"} + /// }; + /// \endcode + AIAS_Right, + /// Don't align array initializer columns. + AIAS_None + }; + /// if not ``None``, when using initialization for an array of structs + /// aligns the fields into columns. + /// + /// \note + /// As of clang-format 15 this option only applied to arrays with equal + /// number of columns per row. + /// \endnote + /// + /// \version 13 + ArrayInitializerAlignmentStyle AlignArrayOfStructures; + + /// Alignment options. + /// + /// They can also be read as a whole for compatibility. The choices are: + /// - None + /// - Consecutive + /// - AcrossEmptyLines + /// - AcrossComments + /// - AcrossEmptyLinesAndComments + /// + /// For example, to align across empty lines and not across comments, either + /// of these work. + /// \code + /// AlignConsecutiveMacros: AcrossEmptyLines + /// + /// AlignConsecutiveMacros: + /// Enabled: true + /// AcrossEmptyLines: true + /// AcrossComments: false + /// \endcode + struct AlignConsecutiveStyle { + /// Whether aligning is enabled. + /// \code + /// #define SHORT_NAME 42 + /// #define LONGER_NAME 0x007f + /// #define EVEN_LONGER_NAME (2) + /// #define foo(x) (x * x) + /// #define bar(y, z) (y + z) + /// + /// int a = 1; + /// int somelongname = 2; + /// double c = 3; + /// + /// int aaaa : 1; + /// int b : 12; + /// int ccc : 8; + /// + /// int aaaa = 12; + /// float b = 23; + /// std::string ccc; + /// \endcode + bool Enabled; + /// Whether to align across empty lines. + /// \code + /// true: + /// int a = 1; + /// int somelongname = 2; + /// double c = 3; + /// + /// int d = 3; + /// + /// false: + /// int a = 1; + /// int somelongname = 2; + /// double c = 3; + /// + /// int d = 3; + /// \endcode + bool AcrossEmptyLines; + /// Whether to align across comments. + /// \code + /// true: + /// int d = 3; + /// /* A comment. */ + /// double e = 4; + /// + /// false: + /// int d = 3; + /// /* A comment. */ + /// double e = 4; + /// \endcode + bool AcrossComments; + /// Only for ``AlignConsecutiveAssignments``. Whether compound assignments + /// like ``+=`` are aligned along with ``=``. + /// \code + /// true: + /// a &= 2; + /// bbb = 2; + /// + /// false: + /// a &= 2; + /// bbb = 2; + /// \endcode + bool AlignCompound; + /// Only for ``AlignConsecutiveDeclarations``. Whether function pointers are + /// aligned. + /// \code + /// true: + /// unsigned i; + /// int &r; + /// int *p; + /// int (*f)(); + /// + /// false: + /// unsigned i; + /// int &r; + /// int *p; + /// int (*f)(); + /// \endcode + bool AlignFunctionPointers; + /// Only for ``AlignConsecutiveAssignments``. Whether short assignment + /// operators are left-padded to the same length as long ones in order to + /// put all assignment operators to the right of the left hand side. + /// \code + /// true: + /// a >>= 2; + /// bbb = 2; + /// + /// a = 2; + /// bbb >>= 2; + /// + /// false: + /// a >>= 2; + /// bbb = 2; + /// + /// a = 2; + /// bbb >>= 2; + /// \endcode + bool PadOperators; + bool operator==(const AlignConsecutiveStyle &R) const { + return Enabled == R.Enabled && AcrossEmptyLines == R.AcrossEmptyLines && + AcrossComments == R.AcrossComments && + AlignCompound == R.AlignCompound && + AlignFunctionPointers == R.AlignFunctionPointers && + PadOperators == R.PadOperators; + } + bool operator!=(const AlignConsecutiveStyle &R) const { + return !(*this == R); + } }; /// Style of aligning consecutive macro definitions. @@ -108,66 +282,8 @@ struct FormatStyle { /// #define foo(x) (x * x) /// #define bar(y, z) (y + z) /// \endcode - /// - /// Possible values: - /// - /// * ``ACS_None`` (in configuration: ``None``) - /// Do not align macro definitions on consecutive lines. - /// - /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``) - /// Align macro definitions on consecutive lines. This will result in - /// formattings like: - /// \code - /// #define SHORT_NAME 42 - /// #define LONGER_NAME 0x007f - /// #define EVEN_LONGER_NAME (2) - /// - /// #define foo(x) (x * x) - /// /* some comment */ - /// #define bar(y, z) (y + z) - /// \endcode - /// - /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) - /// Same as ACS_Consecutive, but also spans over empty lines, e.g. - /// \code - /// #define SHORT_NAME 42 - /// #define LONGER_NAME 0x007f - /// #define EVEN_LONGER_NAME (2) - /// - /// #define foo(x) (x * x) - /// /* some comment */ - /// #define bar(y, z) (y + z) - /// \endcode - /// - /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments, e.g. - /// \code - /// #define SHORT_NAME 42 - /// #define LONGER_NAME 0x007f - /// #define EVEN_LONGER_NAME (2) - /// - /// #define foo(x) (x * x) - /// /* some comment */ - /// #define bar(y, z) (y + z) - /// \endcode - /// - /// * ``ACS_AcrossEmptyLinesAndComments`` - /// (in configuration: ``AcrossEmptyLinesAndComments``) - /// - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments and empty lines, e.g. - /// \code - /// #define SHORT_NAME 42 - /// #define LONGER_NAME 0x007f - /// #define EVEN_LONGER_NAME (2) - /// - /// #define foo(x) (x * x) - /// /* some comment */ - /// #define bar(y, z) (y + z) - /// \endcode + /// \version 9 AlignConsecutiveStyle AlignConsecutiveMacros; - /// Style of aligning consecutive assignments. /// /// ``Consecutive`` will result in formattings like: @@ -176,67 +292,9 @@ struct FormatStyle { /// int somelongname = 2; /// double c = 3; /// \endcode - /// - /// Possible values: - /// - /// * ``ACS_None`` (in configuration: ``None``) - /// Do not align assignments on consecutive lines. - /// - /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``) - /// Align assignments on consecutive lines. This will result in - /// formattings like: - /// \code - /// int a = 1; - /// int somelongname = 2; - /// double c = 3; - /// - /// int d = 3; - /// /* A comment. */ - /// double e = 4; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) - /// Same as ACS_Consecutive, but also spans over empty lines, e.g. - /// \code - /// int a = 1; - /// int somelongname = 2; - /// double c = 3; - /// - /// int d = 3; - /// /* A comment. */ - /// double e = 4; - /// \endcode - /// - /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments, e.g. - /// \code - /// int a = 1; - /// int somelongname = 2; - /// double c = 3; - /// - /// int d = 3; - /// /* A comment. */ - /// double e = 4; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLinesAndComments`` - /// (in configuration: ``AcrossEmptyLinesAndComments``) - /// - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments and empty lines, e.g. - /// \code - /// int a = 1; - /// int somelongname = 2; - /// double c = 3; - /// - /// int d = 3; - /// /* A comment. */ - /// double e = 4; - /// \endcode + /// \version 3.8 AlignConsecutiveStyle AlignConsecutiveAssignments; - - /// Style of aligning consecutive bit field. + /// Style of aligning consecutive bit fields. /// /// ``Consecutive`` will align the bitfield separators of consecutive lines. /// This will result in formattings like: @@ -245,66 +303,8 @@ struct FormatStyle { /// int b : 12; /// int ccc : 8; /// \endcode - /// - /// Possible values: - /// - /// * ``ACS_None`` (in configuration: ``None``) - /// Do not align bit fields on consecutive lines. - /// - /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``) - /// Align bit fields on consecutive lines. This will result in - /// formattings like: - /// \code - /// int aaaa : 1; - /// int b : 12; - /// int ccc : 8; - /// - /// int d : 2; - /// /* A comment. */ - /// int ee : 3; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) - /// Same as ACS_Consecutive, but also spans over empty lines, e.g. - /// \code - /// int aaaa : 1; - /// int b : 12; - /// int ccc : 8; - /// - /// int d : 2; - /// /* A comment. */ - /// int ee : 3; - /// \endcode - /// - /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments, e.g. - /// \code - /// int aaaa : 1; - /// int b : 12; - /// int ccc : 8; - /// - /// int d : 2; - /// /* A comment. */ - /// int ee : 3; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLinesAndComments`` - /// (in configuration: ``AcrossEmptyLinesAndComments``) - /// - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments and empty lines, e.g. - /// \code - /// int aaaa : 1; - /// int b : 12; - /// int ccc : 8; - /// - /// int d : 2; - /// /* A comment. */ - /// int ee : 3; - /// \endcode + /// \version 11 AlignConsecutiveStyle AlignConsecutiveBitFields; - /// Style of aligning consecutive declarations. /// /// ``Consecutive`` will align the declaration names of consecutive lines. @@ -314,68 +314,108 @@ struct FormatStyle { /// float b = 23; /// std::string ccc; /// \endcode - /// - /// Possible values: - /// - /// * ``ACS_None`` (in configuration: ``None``) - /// Do not align bit declarations on consecutive lines. - /// - /// * ``ACS_Consecutive`` (in configuration: ``Consecutive``) - /// Align declarations on consecutive lines. This will result in - /// formattings like: - /// \code - /// int aaaa = 12; - /// float b = 23; - /// std::string ccc; - /// - /// int a = 42; - /// /* A comment. */ - /// bool c = false; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLines`` (in configuration: ``AcrossEmptyLines``) - /// Same as ACS_Consecutive, but also spans over empty lines, e.g. - /// \code - /// int aaaa = 12; - /// float b = 23; - /// std::string ccc; - /// - /// int a = 42; - /// /* A comment. */ - /// bool c = false; - /// \endcode - /// - /// * ``ACS_AcrossComments`` (in configuration: ``AcrossComments``) - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments, e.g. - /// \code - /// int aaaa = 12; - /// float b = 23; - /// std::string ccc; - /// - /// int a = 42; - /// /* A comment. */ - /// bool c = false; - /// \endcode - /// - /// * ``ACS_AcrossEmptyLinesAndComments`` - /// (in configuration: ``AcrossEmptyLinesAndComments``) - /// - /// Same as ACS_Consecutive, but also spans over lines only containing - /// comments and empty lines, e.g. - /// \code - /// int aaaa = 12; - /// float b = 23; - /// std::string ccc; - /// - /// int a = 42; - /// /* A comment. */ - /// bool c = false; - /// \endcode + /// \version 3.8 AlignConsecutiveStyle AlignConsecutiveDeclarations; + /// Alignment options. + /// + struct ShortCaseStatementsAlignmentStyle { + /// Whether aligning is enabled. + /// \code + /// true: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// default: return ""; + /// } + /// + /// false: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// default: return ""; + /// } + /// \endcode + bool Enabled; + /// Whether to align across empty lines. + /// \code + /// true: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// + /// default: return ""; + /// } + /// + /// false: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// + /// default: return ""; + /// } + /// \endcode + bool AcrossEmptyLines; + /// Whether to align across comments. + /// \code + /// true: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// /* A comment. */ + /// default: return ""; + /// } + /// + /// false: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// /* A comment. */ + /// default: return ""; + /// } + /// \endcode + bool AcrossComments; + /// Whether aligned case labels are aligned on the colon, or on the + /// , or on the tokens after the colon. + /// \code + /// true: + /// switch (level) { + /// case log::info : return "info:"; + /// case log::warning: return "warning:"; + /// default : return ""; + /// } + /// + /// false: + /// switch (level) { + /// case log::info: return "info:"; + /// case log::warning: return "warning:"; + /// default: return ""; + /// } + /// \endcode + bool AlignCaseColons; + bool operator==(const ShortCaseStatementsAlignmentStyle &R) const { + return Enabled == R.Enabled && AcrossEmptyLines == R.AcrossEmptyLines && + AcrossComments == R.AcrossComments && + AlignCaseColons == R.AlignCaseColons; + } + }; + + /// Style of aligning consecutive short case labels. + /// Only applies if ``AllowShortCaseLabelsOnASingleLine`` is ``true``. + /// + /// \code{.yaml} + /// # Example of usage: + /// AlignConsecutiveShortCaseStatements: + /// Enabled: true + /// AcrossEmptyLines: true + /// AcrossComments: true + /// AlignCaseColons: false + /// \endcode + /// \version 17 + ShortCaseStatementsAlignmentStyle AlignConsecutiveShortCaseStatements; + /// Different styles for aligning escaped newlines. - enum EscapedNewlineAlignmentStyle : unsigned char { + enum EscapedNewlineAlignmentStyle : int8_t { /// Don't align escaped newlines. /// \code /// #define A \ @@ -406,10 +446,11 @@ struct FormatStyle { }; /// Options for aligning backslashes in escaped newlines. + /// \version 5 EscapedNewlineAlignmentStyle AlignEscapedNewlines; /// Different styles for aligning operands. - enum OperandAlignmentStyle : unsigned char { + enum OperandAlignmentStyle : int8_t { /// Do not align operands of binary and ternary expressions. /// The wrapped lines are indented ``ContinuationIndentWidth`` spaces from /// the start of the line. @@ -444,15 +485,95 @@ struct FormatStyle { /// If ``true``, horizontally align operands of binary and ternary /// expressions. + /// \version 3.5 OperandAlignmentStyle AlignOperands; - /// If ``true``, aligns trailing comments. - /// \code - /// true: false: - /// int a; // My comment a vs. int a; // My comment a - /// int b = 2; // comment b int b = 2; // comment about b + /// Enums for AlignTrailingComments + enum TrailingCommentsAlignmentKinds : int8_t { + /// Leave trailing comments as they are. + /// \code + /// int a; // comment + /// int ab; // comment + /// + /// int abc; // comment + /// int abcd; // comment + /// \endcode + TCAS_Leave, + /// Align trailing comments. + /// \code + /// int a; // comment + /// int ab; // comment + /// + /// int abc; // comment + /// int abcd; // comment + /// \endcode + TCAS_Always, + /// Don't align trailing comments but other formatter applies. + /// \code + /// int a; // comment + /// int ab; // comment + /// + /// int abc; // comment + /// int abcd; // comment + /// \endcode + TCAS_Never, + }; + + /// Alignment options + struct TrailingCommentsAlignmentStyle { + /// Specifies the way to align trailing comments. + TrailingCommentsAlignmentKinds Kind; + /// How many empty lines to apply alignment. + /// When both ``MaxEmptyLinesToKeep`` and ``OverEmptyLines`` are set to 2, + /// it formats like below. + /// \code + /// int a; // all these + /// + /// int ab; // comments are + /// + /// + /// int abcdef; // aligned + /// \endcode + /// + /// When ``MaxEmptyLinesToKeep`` is set to 2 and ``OverEmptyLines`` is set + /// to 1, it formats like below. + /// \code + /// int a; // these are + /// + /// int ab; // aligned + /// + /// + /// int abcdef; // but this isn't + /// \endcode + unsigned OverEmptyLines; + + bool operator==(const TrailingCommentsAlignmentStyle &R) const { + return Kind == R.Kind && OverEmptyLines == R.OverEmptyLines; + } + bool operator!=(const TrailingCommentsAlignmentStyle &R) const { + return !(*this == R); + } + }; + + /// Control of trailing comments. + /// + /// The alignment stops at closing braces after a line break, and only + /// followed by other closing braces, a (``do-``) ``while``, a lambda call, or + /// a semicolon. + /// + /// \note + /// As of clang-format 16 this option is not a bool but can be set + /// to the options. Conventional bool options still can be parsed as before. + /// \endnote + /// + /// \code{.yaml} + /// # Example of usage: + /// AlignTrailingComments: + /// Kind: Always + /// OverEmptyLines: 2 /// \endcode - bool AlignTrailingComments; + /// \version 3.7 + TrailingCommentsAlignmentStyle AlignTrailingComments; /// \brief If a function call or braced initializer list doesn't fit on a /// line, allow putting all arguments onto the next line, even if @@ -468,23 +589,13 @@ struct FormatStyle { /// c, /// d); /// \endcode + /// \version 9 bool AllowAllArgumentsOnNextLine; - /// \brief If a constructor definition with a member initializer list doesn't - /// fit on a single line, allow putting all member initializers onto the next - /// line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true. - /// Note that this parameter has no effect if - /// ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false. - /// \code - /// true: - /// MyClass::MyClass() : - /// member0(0), member1(2) {} - /// - /// false: - /// MyClass::MyClass() : - /// member0(0), - /// member1(2) {} - bool AllowAllConstructorInitializersOnNextLine; + /// This option is **deprecated**. See ``NextLine`` of + /// ``PackConstructorInitializers``. + /// \version 9 + // bool AllowAllConstructorInitializersOnNextLine; /// If the function declaration doesn't fit on a line, /// allow putting all parameters of a function declaration onto @@ -501,25 +612,53 @@ struct FormatStyle { /// int d, /// int e); /// \endcode + /// \version 3.3 bool AllowAllParametersOfDeclarationOnNextLine; - /// Allow short enums on a single line. - /// \code - /// true: - /// enum { A, B } myEnum; - /// - /// false: - /// enum - /// { - /// A, - /// B - /// } myEnum; - /// \endcode - bool AllowShortEnumsOnASingleLine; + /// Different ways to break before a noexcept specifier. + enum BreakBeforeNoexceptSpecifierStyle : int8_t { + /// No line break allowed. + /// \code + /// void foo(int arg1, + /// double arg2) noexcept; + /// + /// void bar(int arg1, double arg2) noexcept( + /// noexcept(baz(arg1)) && + /// noexcept(baz(arg2))); + /// \endcode + BBNSS_Never, + /// For a simple ``noexcept`` there is no line break allowed, but when we + /// have a condition it is. + /// \code + /// void foo(int arg1, + /// double arg2) noexcept; + /// + /// void bar(int arg1, double arg2) + /// noexcept(noexcept(baz(arg1)) && + /// noexcept(baz(arg2))); + /// \endcode + BBNSS_OnlyWithParen, + /// Line breaks are allowed. But note that because of the associated + /// penalties ``clang-format`` often prefers not to break before the + /// ``noexcept``. + /// \code + /// void foo(int arg1, + /// double arg2) noexcept; + /// + /// void bar(int arg1, double arg2) + /// noexcept(noexcept(baz(arg1)) && + /// noexcept(baz(arg2))); + /// \endcode + BBNSS_Always, + }; + + /// Controls if there could be a line break before a ``noexcept`` specifier. + /// \version 18 + BreakBeforeNoexceptSpecifierStyle AllowBreakBeforeNoexceptSpecifier; /// Different styles for merging short blocks containing at most one /// statement. - enum ShortBlockStyle : unsigned char { + enum ShortBlockStyle : int8_t { /// Never merge blocks into a single line. /// \code /// while (true) { @@ -547,6 +686,7 @@ struct FormatStyle { /// Dependent on the value, ``while (true) { continue; }`` can be put on a /// single line. + /// \version 3.5 ShortBlockStyle AllowShortBlocksOnASingleLine; /// If ``true``, short case labels will be contracted to a single line. @@ -560,11 +700,45 @@ struct FormatStyle { /// return; /// } /// \endcode + /// \version 3.6 bool AllowShortCaseLabelsOnASingleLine; + /// Allow short compound requirement on a single line. + /// \code + /// true: + /// template <typename T> + /// concept c = requires(T x) { + /// { x + 1 } -> std::same_as<int>; + /// }; + /// + /// false: + /// template <typename T> + /// concept c = requires(T x) { + /// { + /// x + 1 + /// } -> std::same_as<int>; + /// }; + /// \endcode + /// \version 18 + bool AllowShortCompoundRequirementOnASingleLine; + + /// Allow short enums on a single line. + /// \code + /// true: + /// enum { A, B } myEnum; + /// + /// false: + /// enum { + /// A, + /// B + /// } myEnum; + /// \endcode + /// \version 11 + bool AllowShortEnumsOnASingleLine; + /// Different styles for merging short functions containing at most one /// statement. - enum ShortFunctionStyle : unsigned char { + enum ShortFunctionStyle : int8_t { /// Never merge functions into a single line. SFS_None, /// Only merge functions defined inside a class. Same as "inline", @@ -612,65 +786,104 @@ struct FormatStyle { /// Dependent on the value, ``int f() { return 0; }`` can be put on a /// single line. + /// \version 3.5 ShortFunctionStyle AllowShortFunctionsOnASingleLine; - /// Different styles for handling short if lines - enum ShortIfStyle : unsigned char { + /// Different styles for handling short if statements. + enum ShortIfStyle : int8_t { /// Never put short ifs on the same line. /// \code /// if (a) - /// return ; + /// return; + /// + /// if (b) + /// return; + /// else + /// return; + /// + /// if (c) + /// return; /// else { /// return; /// } /// \endcode SIS_Never, - /// Without else put short ifs on the same line only if - /// the else is not a compound statement. + /// Put short ifs on the same line only if there is no else statement. /// \code /// if (a) return; + /// + /// if (b) + /// return; /// else /// return; + /// + /// if (c) + /// return; + /// else { + /// return; + /// } /// \endcode SIS_WithoutElse, - /// Always put short ifs on the same line if - /// the else is not a compound statement or not. + /// Put short ifs, but not else ifs nor else statements, on the same line. + /// \code + /// if (a) return; + /// + /// if (b) return; + /// else if (b) + /// return; + /// else + /// return; + /// + /// if (c) return; + /// else { + /// return; + /// } + /// \endcode + SIS_OnlyFirstIf, + /// Always put short ifs, else ifs and else statements on the same + /// line. /// \code /// if (a) return; + /// + /// if (b) return; + /// else return; + /// + /// if (c) return; /// else { /// return; /// } /// \endcode - SIS_Always, + SIS_AllIfsAndElse, }; - /// If ``true``, ``if (a) return;`` can be put on a single line. + /// Dependent on the value, ``if (a) return;`` can be put on a single line. + /// \version 3.3 ShortIfStyle AllowShortIfStatementsOnASingleLine; /// Different styles for merging short lambdas containing at most one /// statement. - enum ShortLambdaStyle : unsigned char { + enum ShortLambdaStyle : int8_t { /// Never merge lambdas into a single line. SLS_None, /// Only merge empty lambdas. /// \code - /// auto lambda = [](int a) {} + /// auto lambda = [](int a) {}; /// auto lambda2 = [](int a) { /// return a; /// }; /// \endcode SLS_Empty, - /// Merge lambda into a single line if argument of a function. + /// Merge lambda into a single line if the lambda is argument of a function. /// \code - /// auto lambda = [](int a) { - /// return a; + /// auto lambda = [](int x, int y) { + /// return x < y; /// }; - /// sort(a.begin(), a.end(), ()[] { return x < y; }) + /// sort(a.begin(), a.end(), [](int x, int y) { return x < y; }); /// \endcode SLS_Inline, /// Merge all lambdas fitting on a single line. /// \code - /// auto lambda = [](int a) {} + /// auto lambda = [](int a) {}; /// auto lambda2 = [](int a) { return a; }; /// \endcode SLS_All, @@ -678,15 +891,17 @@ struct FormatStyle { /// Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a /// single line. + /// \version 9 ShortLambdaStyle AllowShortLambdasOnASingleLine; /// If ``true``, ``while (true) continue;`` can be put on a single /// line. + /// \version 3.7 bool AllowShortLoopsOnASingleLine; /// Different ways to break after the function definition return type. /// This option is **deprecated** and is retained for backwards compatibility. - enum DefinitionReturnTypeBreakingStyle : unsigned char { + enum DefinitionReturnTypeBreakingStyle : int8_t { /// Break after return type automatically. /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. DRTBS_None, @@ -698,7 +913,7 @@ struct FormatStyle { /// Different ways to break after the function definition or /// declaration return type. - enum ReturnTypeBreakingStyle : unsigned char { + enum ReturnTypeBreakingStyle : int8_t { /// Break after return type automatically. /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. /// \code @@ -769,9 +984,11 @@ struct FormatStyle { /// The function definition return type breaking style to use. This /// option is **deprecated** and is retained for backwards compatibility. + /// \version 3.7 DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType; /// The function declaration return type breaking style to use. + /// \version 3.8 ReturnTypeBreakingStyle AlwaysBreakAfterReturnType; /// If ``true``, always break before multiline string literals. @@ -786,10 +1003,11 @@ struct FormatStyle { /// "bbbb" "cccc"; /// "cccc"; /// \endcode + /// \version 3.4 bool AlwaysBreakBeforeMultilineStrings; /// Different ways to break after the template declaration. - enum BreakTemplateDeclarationsStyle : unsigned char { + enum BreakTemplateDeclarationsStyle : int8_t { /// Do not force break before declaration. /// ``PenaltyBreakTemplateDeclaration`` is taken into account. /// \code @@ -825,6 +1043,7 @@ struct FormatStyle { }; /// The template declaration breaking style to use. + /// \version 3.4 BreakTemplateDeclarationsStyle AlwaysBreakTemplateDeclarations; /// A vector of strings that should be interpreted as attributes/qualifiers @@ -834,15 +1053,16 @@ struct FormatStyle { /// For example: /// \code /// x = (char *__capability)&y; - /// int function(void) __ununsed; + /// int function(void) __unused; /// void only_writes_to_buffer(char *__output buffer); /// \endcode /// /// In the .clang-format configuration file, this can be configured like: /// \code{.yaml} - /// AttributeMacros: ['__capability', '__output', '__ununsed'] + /// AttributeMacros: ['__capability', '__output', '__unused'] /// \endcode /// + /// \version 12 std::vector<std::string> AttributeMacros; /// If ``false``, a function call's arguments will either be all on the @@ -861,37 +1081,9 @@ struct FormatStyle { /// aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); /// } /// \endcode + /// \version 3.7 bool BinPackArguments; - /// The style of inserting trailing commas into container literals. - enum TrailingCommaStyle : unsigned char { - /// Do not insert trailing commas. - TCS_None, - /// Insert trailing commas in container literals that were wrapped over - /// multiple lines. Note that this is conceptually incompatible with - /// bin-packing, because the trailing comma is used as an indicator - /// that a container should be formatted one-per-line (i.e. not bin-packed). - /// So inserting a trailing comma counteracts bin-packing. - TCS_Wrapped, - }; - - /// If set to ``TCS_Wrapped`` will insert trailing commas in container - /// literals (arrays and objects) that wrap across multiple lines. - /// It is currently only available for JavaScript - /// and disabled by default ``TCS_None``. - /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` - /// as inserting the comma disables bin-packing. - /// \code - /// TSC_Wrapped: - /// const someArray = [ - /// aaaaaaaaaaaaaaaaaaaaaaaaaa, - /// aaaaaaaaaaaaaaaaaaaaaaaaaa, - /// aaaaaaaaaaaaaaaaaaaaaaaaaa, - /// // ^ inserted - /// ] - /// \endcode - TrailingCommaStyle InsertTrailingCommas; - /// If ``false``, a function declaration's or function definition's /// parameters will either all be on the same line or will have one line each. /// \code @@ -904,11 +1096,474 @@ struct FormatStyle { /// int aaaaaaaaaaaaaaaaaaaa, /// int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {} /// \endcode + /// \version 3.7 bool BinPackParameters; + /// Styles for adding spacing around ``:`` in bitfield definitions. + enum BitFieldColonSpacingStyle : int8_t { + /// Add one space on each side of the ``:`` + /// \code + /// unsigned bf : 2; + /// \endcode + BFCS_Both, + /// Add no space around the ``:`` (except when needed for + /// ``AlignConsecutiveBitFields``). + /// \code + /// unsigned bf:2; + /// \endcode + BFCS_None, + /// Add space before the ``:`` only + /// \code + /// unsigned bf :2; + /// \endcode + BFCS_Before, + /// Add space after the ``:`` only (space may be added before if + /// needed for ``AlignConsecutiveBitFields``). + /// \code + /// unsigned bf: 2; + /// \endcode + BFCS_After + }; + /// The BitFieldColonSpacingStyle to use for bitfields. + /// \version 12 + BitFieldColonSpacingStyle BitFieldColonSpacing; + + /// The number of columns to use to indent the contents of braced init lists. + /// If unset, ``ContinuationIndentWidth`` is used. + /// \code + /// AlignAfterOpenBracket: AlwaysBreak + /// BracedInitializerIndentWidth: 2 + /// + /// void f() { + /// SomeClass c{ + /// "foo", + /// "bar", + /// "baz", + /// }; + /// auto s = SomeStruct{ + /// .foo = "foo", + /// .bar = "bar", + /// .baz = "baz", + /// }; + /// SomeArrayT a[3] = { + /// { + /// foo, + /// bar, + /// }, + /// { + /// foo, + /// bar, + /// }, + /// SomeArrayT{}, + /// }; + /// } + /// \endcode + /// \version 17 + std::optional<unsigned> BracedInitializerIndentWidth; + + /// Different ways to wrap braces after control statements. + enum BraceWrappingAfterControlStatementStyle : int8_t { + /// Never wrap braces after a control statement. + /// \code + /// if (foo()) { + /// } else { + /// } + /// for (int i = 0; i < 10; ++i) { + /// } + /// \endcode + BWACS_Never, + /// Only wrap braces after a multi-line control statement. + /// \code + /// if (foo && bar && + /// baz) + /// { + /// quux(); + /// } + /// while (foo || bar) { + /// } + /// \endcode + BWACS_MultiLine, + /// Always wrap braces after a control statement. + /// \code + /// if (foo()) + /// { + /// } else + /// {} + /// for (int i = 0; i < 10; ++i) + /// {} + /// \endcode + BWACS_Always + }; + + /// Precise control over the wrapping of braces. + /// \code + /// # Should be declared this way: + /// BreakBeforeBraces: Custom + /// BraceWrapping: + /// AfterClass: true + /// \endcode + struct BraceWrappingFlags { + /// Wrap case labels. + /// \code + /// false: true: + /// switch (foo) { vs. switch (foo) { + /// case 1: { case 1: + /// bar(); { + /// break; bar(); + /// } break; + /// default: { } + /// plop(); default: + /// } { + /// } plop(); + /// } + /// } + /// \endcode + bool AfterCaseLabel; + /// Wrap class definitions. + /// \code + /// true: + /// class foo + /// {}; + /// + /// false: + /// class foo {}; + /// \endcode + bool AfterClass; + + /// Wrap control statements (``if``/``for``/``while``/``switch``/..). + BraceWrappingAfterControlStatementStyle AfterControlStatement; + /// Wrap enum definitions. + /// \code + /// true: + /// enum X : int + /// { + /// B + /// }; + /// + /// false: + /// enum X : int { B }; + /// \endcode + bool AfterEnum; + /// Wrap function definitions. + /// \code + /// true: + /// void foo() + /// { + /// bar(); + /// bar2(); + /// } + /// + /// false: + /// void foo() { + /// bar(); + /// bar2(); + /// } + /// \endcode + bool AfterFunction; + /// Wrap namespace definitions. + /// \code + /// true: + /// namespace + /// { + /// int foo(); + /// int bar(); + /// } + /// + /// false: + /// namespace { + /// int foo(); + /// int bar(); + /// } + /// \endcode + bool AfterNamespace; + /// Wrap ObjC definitions (interfaces, implementations...). + /// \note + /// @autoreleasepool and @synchronized blocks are wrapped + /// according to ``AfterControlStatement`` flag. + /// \endnote + bool AfterObjCDeclaration; + /// Wrap struct definitions. + /// \code + /// true: + /// struct foo + /// { + /// int x; + /// }; + /// + /// false: + /// struct foo { + /// int x; + /// }; + /// \endcode + bool AfterStruct; + /// Wrap union definitions. + /// \code + /// true: + /// union foo + /// { + /// int x; + /// } + /// + /// false: + /// union foo { + /// int x; + /// } + /// \endcode + bool AfterUnion; + /// Wrap extern blocks. + /// \code + /// true: + /// extern "C" + /// { + /// int foo(); + /// } + /// + /// false: + /// extern "C" { + /// int foo(); + /// } + /// \endcode + bool AfterExternBlock; // Partially superseded by IndentExternBlock + /// Wrap before ``catch``. + /// \code + /// true: + /// try { + /// foo(); + /// } + /// catch () { + /// } + /// + /// false: + /// try { + /// foo(); + /// } catch () { + /// } + /// \endcode + bool BeforeCatch; + /// Wrap before ``else``. + /// \code + /// true: + /// if (foo()) { + /// } + /// else { + /// } + /// + /// false: + /// if (foo()) { + /// } else { + /// } + /// \endcode + bool BeforeElse; + /// Wrap lambda block. + /// \code + /// true: + /// connect( + /// []() + /// { + /// foo(); + /// bar(); + /// }); + /// + /// false: + /// connect([]() { + /// foo(); + /// bar(); + /// }); + /// \endcode + bool BeforeLambdaBody; + /// Wrap before ``while``. + /// \code + /// true: + /// do { + /// foo(); + /// } + /// while (1); + /// + /// false: + /// do { + /// foo(); + /// } while (1); + /// \endcode + bool BeforeWhile; + /// Indent the wrapped braces themselves. + bool IndentBraces; + /// If ``false``, empty function body can be put on a single line. + /// This option is used only if the opening brace of the function has + /// already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is + /// set, and the function could/should not be put on a single line (as per + /// ``AllowShortFunctionsOnASingleLine`` and constructor formatting + /// options). + /// \code + /// false: true: + /// int f() vs. int f() + /// {} { + /// } + /// \endcode + /// + bool SplitEmptyFunction; + /// If ``false``, empty record (e.g. class, struct or union) body + /// can be put on a single line. This option is used only if the opening + /// brace of the record has already been wrapped, i.e. the ``AfterClass`` + /// (for classes) brace wrapping mode is set. + /// \code + /// false: true: + /// class Foo vs. class Foo + /// {} { + /// } + /// \endcode + /// + bool SplitEmptyRecord; + /// If ``false``, empty namespace body can be put on a single line. + /// This option is used only if the opening brace of the namespace has + /// already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is + /// set. + /// \code + /// false: true: + /// namespace Foo vs. namespace Foo + /// {} { + /// } + /// \endcode + /// + bool SplitEmptyNamespace; + }; + + /// Control of individual brace wrapping cases. + /// + /// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how + /// each individual brace case should be handled. Otherwise, this is ignored. + /// \code{.yaml} + /// # Example of usage: + /// BreakBeforeBraces: Custom + /// BraceWrapping: + /// AfterEnum: true + /// AfterStruct: false + /// SplitEmptyFunction: false + /// \endcode + /// \version 3.8 + BraceWrappingFlags BraceWrapping; + + /// Break between adjacent string literals. + /// \code + /// true: + /// return "Code" + /// "\0\52\26\55\55\0" + /// "x013" + /// "\02\xBA"; + /// false: + /// return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA"; + /// \endcode + /// \version 18 + bool BreakAdjacentStringLiterals; + + /// Different ways to break after attributes. + enum AttributeBreakingStyle : int8_t { + /// Always break after attributes. + /// \code + /// [[maybe_unused]] + /// const int i; + /// [[gnu::const]] [[maybe_unused]] + /// int j; + /// + /// [[nodiscard]] + /// inline int f(); + /// [[gnu::const]] [[nodiscard]] + /// int g(); + /// + /// [[likely]] + /// if (a) + /// f(); + /// else + /// g(); + /// + /// switch (b) { + /// [[unlikely]] + /// case 1: + /// ++b; + /// break; + /// [[likely]] + /// default: + /// return; + /// } + /// \endcode + ABS_Always, + /// Leave the line breaking after attributes as is. + /// \code + /// [[maybe_unused]] const int i; + /// [[gnu::const]] [[maybe_unused]] + /// int j; + /// + /// [[nodiscard]] inline int f(); + /// [[gnu::const]] [[nodiscard]] + /// int g(); + /// + /// [[likely]] if (a) + /// f(); + /// else + /// g(); + /// + /// switch (b) { + /// [[unlikely]] case 1: + /// ++b; + /// break; + /// [[likely]] + /// default: + /// return; + /// } + /// \endcode + ABS_Leave, + /// Never break after attributes. + /// \code + /// [[maybe_unused]] const int i; + /// [[gnu::const]] [[maybe_unused]] int j; + /// + /// [[nodiscard]] inline int f(); + /// [[gnu::const]] [[nodiscard]] int g(); + /// + /// [[likely]] if (a) + /// f(); + /// else + /// g(); + /// + /// switch (b) { + /// [[unlikely]] case 1: + /// ++b; + /// break; + /// [[likely]] default: + /// return; + /// } + /// \endcode + ABS_Never, + }; + + /// Break after a group of C++11 attributes before variable or function + /// (including constructor/destructor) declaration/definition names or before + /// control statements, i.e. ``if``, ``switch`` (including ``case`` and + /// ``default`` labels), ``for``, and ``while`` statements. + /// \version 16 + AttributeBreakingStyle BreakAfterAttributes; + + /// If ``true``, clang-format will always break after a Json array ``[`` + /// otherwise it will scan until the closing ``]`` to determine if it should + /// add newlines between elements (prettier compatible). + /// + /// \note + /// This is currently only for formatting JSON. + /// \endnote + /// \code + /// true: false: + /// [ vs. [1, 2, 3, 4] + /// 1, + /// 2, + /// 3, + /// 4 + /// ] + /// \endcode + /// \version 16 + bool BreakArrays; + /// The style of wrapping parameters on the same line (bin-packed) or /// on one line each. - enum BinPackStyle : unsigned char { + enum BinPackStyle : int8_t { /// Automatically determine parameter bin-packing behavior. BPS_Auto, /// Always bin-pack parameters. @@ -918,7 +1573,7 @@ struct FormatStyle { }; /// The style of breaking before or after binary operators. - enum BinaryOperatorStyle : unsigned char { + enum BinaryOperatorStyle : int8_t { /// Break after operators. /// \code /// LooooooooooongType loooooooooooooooooooooongVariable = @@ -958,10 +1613,11 @@ struct FormatStyle { }; /// The way to wrap binary operators. + /// \version 3.6 BinaryOperatorStyle BreakBeforeBinaryOperators; /// Different ways to attach braces to their surrounding context. - enum BraceBreakingStyle : unsigned char { + enum BraceBreakingStyle : int8_t { /// Always attach braces to surrounding context. /// \code /// namespace N { @@ -1387,297 +2043,66 @@ struct FormatStyle { /// } // namespace N /// \endcode BS_WebKit, - /// Configure each individual brace in `BraceWrapping`. + /// Configure each individual brace in ``BraceWrapping``. BS_Custom }; /// The brace breaking style to use. + /// \version 3.7 BraceBreakingStyle BreakBeforeBraces; - /// Different ways to wrap braces after control statements. - enum BraceWrappingAfterControlStatementStyle : unsigned char { - /// Never wrap braces after a control statement. - /// \code - /// if (foo()) { - /// } else { - /// } - /// for (int i = 0; i < 10; ++i) { - /// } - /// \endcode - BWACS_Never, - /// Only wrap braces after a multi-line control statement. + /// Different ways to break before concept declarations. + enum BreakBeforeConceptDeclarationsStyle : int8_t { + /// Keep the template declaration line together with ``concept``. /// \code - /// if (foo && bar && - /// baz) - /// { - /// quux(); - /// } - /// while (foo || bar) { - /// } + /// template <typename T> concept C = ...; /// \endcode - BWACS_MultiLine, - /// Always wrap braces after a control statement. + BBCDS_Never, + /// Breaking between template declaration and ``concept`` is allowed. The + /// actual behavior depends on the content and line breaking rules and + /// penalties. + BBCDS_Allowed, + /// Always break before ``concept``, putting it in the line after the + /// template declaration. /// \code - /// if (foo()) - /// { - /// } else - /// {} - /// for (int i = 0; i < 10; ++i) - /// {} + /// template <typename T> + /// concept C = ...; /// \endcode - BWACS_Always + BBCDS_Always, }; - /// Precise control over the wrapping of braces. - /// \code - /// # Should be declared this way: - /// BreakBeforeBraces: Custom - /// BraceWrapping: - /// AfterClass: true - /// \endcode - struct BraceWrappingFlags { - /// Wrap case labels. - /// \code - /// false: true: - /// switch (foo) { vs. switch (foo) { - /// case 1: { case 1: - /// bar(); { - /// break; bar(); - /// } break; - /// default: { } - /// plop(); default: - /// } { - /// } plop(); - /// } - /// } - /// \endcode - bool AfterCaseLabel; - /// Wrap class definitions. - /// \code - /// true: - /// class foo {}; - /// - /// false: - /// class foo - /// {}; - /// \endcode - bool AfterClass; + /// The concept declaration style to use. + /// \version 12 + BreakBeforeConceptDeclarationsStyle BreakBeforeConceptDeclarations; - /// Wrap control statements (``if``/``for``/``while``/``switch``/..). - BraceWrappingAfterControlStatementStyle AfterControlStatement; - /// Wrap enum definitions. - /// \code - /// true: - /// enum X : int - /// { - /// B - /// }; - /// - /// false: - /// enum X : int { B }; - /// \endcode - bool AfterEnum; - /// Wrap function definitions. - /// \code - /// true: - /// void foo() - /// { - /// bar(); - /// bar2(); - /// } - /// - /// false: - /// void foo() { - /// bar(); - /// bar2(); - /// } - /// \endcode - bool AfterFunction; - /// Wrap namespace definitions. + /// Different ways to break ASM parameters. + enum BreakBeforeInlineASMColonStyle : int8_t { + /// No break before inline ASM colon. /// \code - /// true: - /// namespace - /// { - /// int foo(); - /// int bar(); - /// } - /// - /// false: - /// namespace { - /// int foo(); - /// int bar(); - /// } + /// asm volatile("string", : : val); /// \endcode - bool AfterNamespace; - /// Wrap ObjC definitions (interfaces, implementations...). - /// \note @autoreleasepool and @synchronized blocks are wrapped - /// according to `AfterControlStatement` flag. - bool AfterObjCDeclaration; - /// Wrap struct definitions. + BBIAS_Never, + /// Break before inline ASM colon if the line length is longer than column + /// limit. /// \code - /// true: - /// struct foo - /// { - /// int x; - /// }; - /// - /// false: - /// struct foo { - /// int x; - /// }; + /// asm volatile("string", : : val); + /// asm("cmoveq %1, %2, %[result]" + /// : [result] "=r"(result) + /// : "r"(test), "r"(new), "[result]"(old)); /// \endcode - bool AfterStruct; - /// Wrap union definitions. + BBIAS_OnlyMultiline, + /// Always break before inline ASM colon. /// \code - /// true: - /// union foo - /// { - /// int x; - /// } - /// - /// false: - /// union foo { - /// int x; - /// } + /// asm volatile("string", + /// : + /// : val); /// \endcode - bool AfterUnion; - /// Wrap extern blocks. - /// \code - /// true: - /// extern "C" - /// { - /// int foo(); - /// } - /// - /// false: - /// extern "C" { - /// int foo(); - /// } - /// \endcode - bool AfterExternBlock; // Partially superseded by IndentExternBlock - /// Wrap before ``catch``. - /// \code - /// true: - /// try { - /// foo(); - /// } - /// catch () { - /// } - /// - /// false: - /// try { - /// foo(); - /// } catch () { - /// } - /// \endcode - bool BeforeCatch; - /// Wrap before ``else``. - /// \code - /// true: - /// if (foo()) { - /// } - /// else { - /// } - /// - /// false: - /// if (foo()) { - /// } else { - /// } - /// \endcode - bool BeforeElse; - /// Wrap lambda block. - /// \code - /// true: - /// connect( - /// []() - /// { - /// foo(); - /// bar(); - /// }); - /// - /// false: - /// connect([]() { - /// foo(); - /// bar(); - /// }); - /// \endcode - bool BeforeLambdaBody; - /// Wrap before ``while``. - /// \code - /// true: - /// do { - /// foo(); - /// } - /// while (1); - /// - /// false: - /// do { - /// foo(); - /// } while (1); - /// \endcode - bool BeforeWhile; - /// Indent the wrapped braces themselves. - bool IndentBraces; - /// If ``false``, empty function body can be put on a single line. - /// This option is used only if the opening brace of the function has - /// already been wrapped, i.e. the `AfterFunction` brace wrapping mode is - /// set, and the function could/should not be put on a single line (as per - /// `AllowShortFunctionsOnASingleLine` and constructor formatting options). - /// \code - /// int f() vs. int f() - /// {} { - /// } - /// \endcode - /// - bool SplitEmptyFunction; - /// If ``false``, empty record (e.g. class, struct or union) body - /// can be put on a single line. This option is used only if the opening - /// brace of the record has already been wrapped, i.e. the `AfterClass` - /// (for classes) brace wrapping mode is set. - /// \code - /// class Foo vs. class Foo - /// {} { - /// } - /// \endcode - /// - bool SplitEmptyRecord; - /// If ``false``, empty namespace body can be put on a single line. - /// This option is used only if the opening brace of the namespace has - /// already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is - /// set. - /// \code - /// namespace Foo vs. namespace Foo - /// {} { - /// } - /// \endcode - /// - bool SplitEmptyNamespace; + BBIAS_Always, }; - /// Control of individual brace wrapping cases. - /// - /// If ``BreakBeforeBraces`` is set to ``BS_Custom``, use this to specify how - /// each individual brace case should be handled. Otherwise, this is ignored. - /// \code{.yaml} - /// # Example of usage: - /// BreakBeforeBraces: Custom - /// BraceWrapping: - /// AfterEnum: true - /// AfterStruct: false - /// SplitEmptyFunction: false - /// \endcode - BraceWrappingFlags BraceWrapping; - - /// If ``true``, concept will be placed on a new line. - /// \code - /// true: - /// template<typename T> - /// concept ... - /// - /// false: - /// template<typename T> concept ... - /// \endcode - bool BreakBeforeConceptDeclarations; + /// The inline ASM colon style to use. + /// \version 16 + BreakBeforeInlineASMColonStyle BreakBeforeInlineASMColon; /// If ``true``, ternary operators will be placed after line breaks. /// \code @@ -1691,10 +2116,11 @@ struct FormatStyle { /// firstValue : /// SecondValueVeryVeryVeryVeryLong; /// \endcode + /// \version 3.7 bool BreakBeforeTernaryOperators; /// Different ways to break initializers. - enum BreakConstructorInitializersStyle : unsigned char { + enum BreakConstructorInitializersStyle : int8_t { /// Break constructor initializers before the colon and after the commas. /// \code /// Constructor() @@ -1719,7 +2145,8 @@ struct FormatStyle { BCIS_AfterColon }; - /// The constructor initializers style to use. + /// The break constructor initializers style to use. + /// \version 5 BreakConstructorInitializersStyle BreakConstructorInitializers; /// Break after each annotation on a field in Java files. @@ -1729,9 +2156,12 @@ struct FormatStyle { /// @Mock /// DataLoad loader; /// \endcode + /// \version 3.8 bool BreakAfterJavaFieldAnnotations; /// Allow breaking string literals when formatting. + /// + /// In C, C++, and Objective-C: /// \code /// true: /// const char* x = "veryVeryVeryVeryVeryVe" @@ -1740,8 +2170,36 @@ struct FormatStyle { /// /// false: /// const char* x = - /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; + /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; + /// \endcode + /// + /// In C# and Java: + /// \code + /// true: + /// string x = "veryVeryVeryVeryVeryVe" + + /// "ryVeryVeryVeryVeryVery" + + /// "VeryLongString"; + /// + /// false: + /// string x = + /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; + /// \endcode + /// + /// C# interpolated strings are not broken. + /// + /// In Verilog: + /// \code + /// true: + /// string x = {"veryVeryVeryVeryVeryVe", + /// "ryVeryVeryVeryVeryVery", + /// "VeryLongString"}; + /// + /// false: + /// string x = + /// "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; /// \endcode + /// + /// \version 3.9 bool BreakStringLiterals; /// The column limit. @@ -1749,6 +2207,7 @@ struct FormatStyle { /// A column limit of ``0`` means that there is no column limit. In this case, /// clang-format will respect the input's line breaking decisions within /// statements unless they contradict other rules. + /// \version 3.7 unsigned ColumnLimit; /// A regular expression that describes comments with special meaning, @@ -1758,10 +2217,11 @@ struct FormatStyle { /// // Will leave the following line unaffected /// #include <vector> // FOOBAR pragma: keep /// \endcode + /// \version 3.7 std::string CommentPragmas; /// Different ways to break inheritance list. - enum BreakInheritanceListStyle : unsigned char { + enum BreakInheritanceListStyle : int8_t { /// Break inheritance list before the colon and after the commas. /// \code /// class Foo @@ -1786,10 +2246,18 @@ struct FormatStyle { /// Base2 /// {}; /// \endcode - BILS_AfterColon + BILS_AfterColon, + /// Break inheritance list only after the commas. + /// \code + /// class Foo : Base1, + /// Base2 + /// {}; + /// \endcode + BILS_AfterComma, }; /// The inheritance list style to use. + /// \version 7 BreakInheritanceListStyle BreakInheritanceList; /// If ``true``, consecutive namespace declarations will be on the same @@ -1813,30 +2281,17 @@ struct FormatStyle { /// namespace Extra { /// }}} /// \endcode + /// \version 5 bool CompactNamespaces; - // clang-format off - /// If the constructor initializers don't fit on a line, put each - /// initializer on its own line. - /// \code - /// true: - /// SomeClass::Constructor() - /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { - /// return 0; - /// } - /// - /// false: - /// SomeClass::Constructor() - /// : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), - /// aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) { - /// return 0; - /// } - /// \endcode - bool ConstructorInitializerAllOnOneLineOrOnePerLine; - // clang-format on + /// This option is **deprecated**. See ``CurrentLine`` of + /// ``PackConstructorInitializers``. + /// \version 3.7 + // bool ConstructorInitializerAllOnOneLineOrOnePerLine; /// The number of characters to use for indentation of constructor /// initializer lists as well as inheritance lists. + /// \version 3.7 unsigned ConstructorInitializerIndentWidth; /// Indent width for line continuations. @@ -1847,6 +2302,7 @@ struct FormatStyle { /// longFunction( // Again a long comment /// arg); /// \endcode + /// \version 3.7 unsigned ContinuationIndentWidth; /// If ``true``, format braced lists as best suited for C++11 braced @@ -1869,24 +2325,79 @@ struct FormatStyle { /// f(MyMap[{composite, key}]); f(MyMap[{ composite, key }]); /// new int[3]{1, 2, 3}; new int[3]{ 1, 2, 3 }; /// \endcode + /// \version 3.4 bool Cpp11BracedListStyle; - /// \brief Analyze the formatted file for the most used line ending (``\r\n`` - /// or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived. - bool DeriveLineEnding; + /// This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of + /// ``LineEnding``. + /// \version 10 + // bool DeriveLineEnding; /// If ``true``, analyze the formatted file for the most common /// alignment of ``&`` and ``*``. /// Pointer and reference alignment styles are going to be updated according /// to the preferences found in the file. /// ``PointerAlignment`` is then used only as fallback. + /// \version 3.7 bool DerivePointerAlignment; /// Disables formatting completely. + /// \version 3.7 bool DisableFormat; + /// Different styles for empty line after access modifiers. + /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of + /// empty lines between two access modifiers. + enum EmptyLineAfterAccessModifierStyle : int8_t { + /// Remove all empty lines after access modifiers. + /// \code + /// struct foo { + /// private: + /// int i; + /// protected: + /// int j; + /// /* comment */ + /// public: + /// foo() {} + /// private: + /// protected: + /// }; + /// \endcode + ELAAMS_Never, + /// Keep existing empty lines after access modifiers. + /// MaxEmptyLinesToKeep is applied instead. + ELAAMS_Leave, + /// Always add empty line after access modifiers if there are none. + /// MaxEmptyLinesToKeep is applied also. + /// \code + /// struct foo { + /// private: + /// + /// int i; + /// protected: + /// + /// int j; + /// /* comment */ + /// public: + /// + /// foo() {} + /// private: + /// + /// protected: + /// + /// }; + /// \endcode + ELAAMS_Always, + }; + + /// Defines when to put an empty line after access modifiers. + /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of + /// empty lines between two access modifiers. + /// \version 13 + EmptyLineAfterAccessModifierStyle EmptyLineAfterAccessModifier; + /// Different styles for empty line before access modifiers. - enum EmptyLineBeforeAccessModifierStyle : unsigned char { + enum EmptyLineBeforeAccessModifierStyle : int8_t { /// Remove all empty lines before access modifiers. /// \code /// struct foo { @@ -1945,6 +2456,7 @@ struct FormatStyle { }; /// Defines in which cases to put empty line before access modifiers. + /// \version 12 EmptyLineBeforeAccessModifierStyle EmptyLineBeforeAccessModifier; /// If ``true``, clang-format detects whether function calls and @@ -1955,18 +2467,27 @@ struct FormatStyle { /// made, clang-format analyzes whether there are other bin-packed cases in /// the input file and act accordingly. /// - /// NOTE: This is an experimental flag, that might go away or be renamed. Do - /// not use this in config files, etc. Use at your own risk. + /// \note + /// This is an experimental flag, that might go away or be renamed. Do + /// not use this in config files, etc. Use at your own risk. + /// \endnote + /// \version 3.7 bool ExperimentalAutoDetectBinPacking; - /// If ``true``, clang-format adds missing namespace end comments and - /// fixes invalid existing ones. + /// If ``true``, clang-format adds missing namespace end comments for + /// namespaces and fixes invalid existing ones. This doesn't affect short + /// namespaces, which are controlled by ``ShortNamespaceLines``. /// \code /// true: false: - /// namespace a { vs. namespace a { - /// foo(); foo(); + /// namespace longNamespace { vs. namespace longNamespace { + /// void foo(); void foo(); + /// void bar(); void bar(); /// } // namespace a } + /// namespace shortNamespace { namespace shortNamespace { + /// void baz(); void baz(); + /// } } /// \endcode + /// \version 5 bool FixNamespaceComments; /// A vector of macros that should be interpreted as foreach loops @@ -1984,81 +2505,58 @@ struct FormatStyle { /// \endcode /// /// For example: BOOST_FOREACH. + /// \version 3.7 std::vector<std::string> ForEachMacros; - /// \brief A vector of macros that should be interpreted as type declarations - /// instead of as function calls. - /// - /// These are expected to be macros of the form: - /// \code - /// STACK_OF(...) - /// \endcode - /// - /// In the .clang-format configuration file, this can be configured like: - /// \code{.yaml} - /// TypenameMacros: ['STACK_OF', 'LIST'] - /// \endcode - /// - /// For example: OpenSSL STACK_OF, BSD LIST_ENTRY. - std::vector<std::string> TypenameMacros; - - /// A vector of macros that should be interpreted as complete - /// statements. - /// - /// Typical macros are expressions, and require a semi-colon to be - /// added; sometimes this is not the case, and this allows to make - /// clang-format aware of such cases. - /// - /// For example: Q_UNUSED - std::vector<std::string> StatementMacros; - - /// A vector of macros which are used to open namespace blocks. - /// - /// These are expected to be macros of the form: - /// \code - /// NAMESPACE(<namespace-name>, ...) { - /// <namespace-content> - /// } - /// \endcode - /// - /// For example: TESTSUITE - std::vector<std::string> NamespaceMacros; + tooling::IncludeStyle IncludeStyle; - /// A vector of macros which are whitespace-sensitive and should not - /// be touched. + /// A vector of macros that should be interpreted as conditionals + /// instead of as function calls. /// /// These are expected to be macros of the form: /// \code - /// STRINGIZE(...) + /// IF(...) + /// <conditional-body> + /// else IF(...) + /// <conditional-body> /// \endcode /// /// In the .clang-format configuration file, this can be configured like: /// \code{.yaml} - /// WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE'] + /// IfMacros: ['IF'] /// \endcode /// - /// For example: BOOST_PP_STRINGIZE - std::vector<std::string> WhitespaceSensitiveMacros; - - tooling::IncludeStyle IncludeStyle; + /// For example: `KJ_IF_MAYBE + /// <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_ + /// \version 13 + std::vector<std::string> IfMacros; - /// Indent case labels one level from the switch statement. + /// Specify whether access modifiers should have their own indentation level. /// - /// When ``false``, use the same indentation level as for the switch - /// statement. Switch statement body is always indented one level more than - /// case labels (except the first block following the case label, which - /// itself indents the code - unless IndentCaseBlocks is enabled). + /// When ``false``, access modifiers are indented (or outdented) relative to + /// the record members, respecting the ``AccessModifierOffset``. Record + /// members are indented one level below the record. + /// When ``true``, access modifiers get their own indentation level. As a + /// consequence, record members are always indented 2 levels below the record, + /// regardless of the access modifier presence. Value of the + /// ``AccessModifierOffset`` is ignored. /// \code /// false: true: - /// switch (fool) { vs. switch (fool) { - /// case 1: case 1: - /// bar(); bar(); - /// break; break; - /// default: default: - /// plop(); plop(); + /// class C { vs. class C { + /// class D { class D { + /// void bar(); void bar(); + /// protected: protected: + /// D(); D(); + /// }; }; + /// public: public: + /// C(); C(); + /// }; }; + /// void foo() { void foo() { + /// return 1; return 1; /// } } /// \endcode - bool IndentCaseLabels; + /// \version 13 + bool IndentAccessModifiers; /// Indent case label blocks one level from the case label. /// @@ -2080,8 +2578,28 @@ struct FormatStyle { /// } /// } /// \endcode + /// \version 11 bool IndentCaseBlocks; + /// Indent case labels one level from the switch statement. + /// + /// When ``false``, use the same indentation level as for the switch + /// statement. Switch statement body is always indented one level more than + /// case labels (except the first block following the case label, which + /// itself indents the code - unless IndentCaseBlocks is enabled). + /// \code + /// false: true: + /// switch (fool) { vs. switch (fool) { + /// case 1: case 1: + /// bar(); bar(); + /// break; break; + /// default: default: + /// plop(); plop(); + /// } } + /// \endcode + /// \version 3.3 + bool IndentCaseLabels; + /// Indent goto labels. /// /// When ``false``, goto labels are flushed left. @@ -2096,44 +2614,11 @@ struct FormatStyle { /// return 1; return 1; /// } } /// \endcode + /// \version 10 bool IndentGotoLabels; - /// Options for indenting preprocessor directives. - enum PPDirectiveIndentStyle : unsigned char { - /// Does not indent any directives. - /// \code - /// #if FOO - /// #if BAR - /// #include <foo> - /// #endif - /// #endif - /// \endcode - PPDIS_None, - /// Indents directives after the hash. - /// \code - /// #if FOO - /// # if BAR - /// # include <foo> - /// # endif - /// #endif - /// \endcode - PPDIS_AfterHash, - /// Indents directives before the hash. - /// \code - /// #if FOO - /// #if BAR - /// #include <foo> - /// #endif - /// #endif - /// \endcode - PPDIS_BeforeHash - }; - - /// The preprocessor directive indenting style to use. - PPDirectiveIndentStyle IndentPPDirectives; - /// Indents extern blocks - enum IndentExternBlockStyle : unsigned char { + enum IndentExternBlockStyle : int8_t { /// Backwards compatible with AfterExternBlock's indenting. /// \code /// IndentExternBlock: AfterExternBlock @@ -2169,9 +2654,48 @@ struct FormatStyle { }; /// IndentExternBlockStyle is the type of indenting of extern blocks. + /// \version 11 IndentExternBlockStyle IndentExternBlock; - /// Indent the requires clause in a template + /// Options for indenting preprocessor directives. + enum PPDirectiveIndentStyle : int8_t { + /// Does not indent any directives. + /// \code + /// #if FOO + /// #if BAR + /// #include <foo> + /// #endif + /// #endif + /// \endcode + PPDIS_None, + /// Indents directives after the hash. + /// \code + /// #if FOO + /// # if BAR + /// # include <foo> + /// # endif + /// #endif + /// \endcode + PPDIS_AfterHash, + /// Indents directives before the hash. + /// \code + /// #if FOO + /// #if BAR + /// #include <foo> + /// #endif + /// #endif + /// \endcode + PPDIS_BeforeHash + }; + + /// The preprocessor directive indenting style to use. + /// \version 6 + PPDirectiveIndentStyle IndentPPDirectives; + + /// Indent the requires clause in a template. This only applies when + /// ``RequiresClausePosition`` is ``OwnLine``, or ``WithFollowing``. + /// + /// In clang-format 12, 13 and 14 it was named ``IndentRequires``. /// \code /// true: /// template <typename It> @@ -2187,7 +2711,8 @@ struct FormatStyle { /// //.... /// } /// \endcode - bool IndentRequires; + /// \version 15 + bool IndentRequiresClause; /// The number of columns to use for indentation. /// \code @@ -2200,6 +2725,7 @@ struct FormatStyle { /// } /// } /// \endcode + /// \version 3.7 unsigned IndentWidth; /// Indent if a function definition or declaration is wrapped after the @@ -2213,8 +2739,154 @@ struct FormatStyle { /// LoooooooooooooooooooooooooooooooooooooooongReturnType /// LoooooooooooooooooooooooooooooooongFunctionDeclaration(); /// \endcode + /// \version 3.7 bool IndentWrappedFunctionNames; + /// Insert braces after control statements (``if``, ``else``, ``for``, ``do``, + /// and ``while``) in C++ unless the control statements are inside macro + /// definitions or the braces would enclose preprocessor directives. + /// \warning + /// Setting this option to ``true`` could lead to incorrect code formatting + /// due to clang-format's lack of complete semantic information. As such, + /// extra care should be taken to review code changes made by this option. + /// \endwarning + /// \code + /// false: true: + /// + /// if (isa<FunctionDecl>(D)) vs. if (isa<FunctionDecl>(D)) { + /// handleFunctionDecl(D); handleFunctionDecl(D); + /// else if (isa<VarDecl>(D)) } else if (isa<VarDecl>(D)) { + /// handleVarDecl(D); handleVarDecl(D); + /// else } else { + /// return; return; + /// } + /// + /// while (i--) vs. while (i--) { + /// for (auto *A : D.attrs()) for (auto *A : D.attrs()) { + /// handleAttr(A); handleAttr(A); + /// } + /// } + /// + /// do vs. do { + /// --i; --i; + /// while (i); } while (i); + /// \endcode + /// \version 15 + bool InsertBraces; + + /// Insert a newline at end of file if missing. + /// \version 16 + bool InsertNewlineAtEOF; + + /// The style of inserting trailing commas into container literals. + enum TrailingCommaStyle : int8_t { + /// Do not insert trailing commas. + TCS_None, + /// Insert trailing commas in container literals that were wrapped over + /// multiple lines. Note that this is conceptually incompatible with + /// bin-packing, because the trailing comma is used as an indicator + /// that a container should be formatted one-per-line (i.e. not bin-packed). + /// So inserting a trailing comma counteracts bin-packing. + TCS_Wrapped, + }; + + /// If set to ``TCS_Wrapped`` will insert trailing commas in container + /// literals (arrays and objects) that wrap across multiple lines. + /// It is currently only available for JavaScript + /// and disabled by default ``TCS_None``. + /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments`` + /// as inserting the comma disables bin-packing. + /// \code + /// TSC_Wrapped: + /// const someArray = [ + /// aaaaaaaaaaaaaaaaaaaaaaaaaa, + /// aaaaaaaaaaaaaaaaaaaaaaaaaa, + /// aaaaaaaaaaaaaaaaaaaaaaaaaa, + /// // ^ inserted + /// ] + /// \endcode + /// \version 11 + TrailingCommaStyle InsertTrailingCommas; + + /// Separator format of integer literals of different bases. + /// + /// If negative, remove separators. If ``0``, leave the literal as is. If + /// positive, insert separators between digits starting from the rightmost + /// digit. + /// + /// For example, the config below will leave separators in binary literals + /// alone, insert separators in decimal literals to separate the digits into + /// groups of 3, and remove separators in hexadecimal literals. + /// \code + /// IntegerLiteralSeparator: + /// Binary: 0 + /// Decimal: 3 + /// Hex: -1 + /// \endcode + /// + /// You can also specify a minimum number of digits (``BinaryMinDigits``, + /// ``DecimalMinDigits``, and ``HexMinDigits``) the integer literal must + /// have in order for the separators to be inserted. + struct IntegerLiteralSeparatorStyle { + /// Format separators in binary literals. + /// \code{.text} + /// /* -1: */ b = 0b100111101101; + /// /* 0: */ b = 0b10011'11'0110'1; + /// /* 3: */ b = 0b100'111'101'101; + /// /* 4: */ b = 0b1001'1110'1101; + /// \endcode + int8_t Binary; + /// Format separators in binary literals with a minimum number of digits. + /// \code{.text} + /// // Binary: 3 + /// // BinaryMinDigits: 7 + /// b1 = 0b101101; + /// b2 = 0b1'101'101; + /// \endcode + int8_t BinaryMinDigits; + /// Format separators in decimal literals. + /// \code{.text} + /// /* -1: */ d = 18446744073709550592ull; + /// /* 0: */ d = 184467'440737'0'95505'92ull; + /// /* 3: */ d = 18'446'744'073'709'550'592ull; + /// \endcode + int8_t Decimal; + /// Format separators in decimal literals with a minimum number of digits. + /// \code{.text} + /// // Decimal: 3 + /// // DecimalMinDigits: 5 + /// d1 = 2023; + /// d2 = 10'000; + /// \endcode + int8_t DecimalMinDigits; + /// Format separators in hexadecimal literals. + /// \code{.text} + /// /* -1: */ h = 0xDEADBEEFDEADBEEFuz; + /// /* 0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz; + /// /* 2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz; + /// \endcode + int8_t Hex; + /// Format separators in hexadecimal literals with a minimum number of + /// digits. + /// \code{.text} + /// // Hex: 2 + /// // HexMinDigits: 6 + /// h1 = 0xABCDE; + /// h2 = 0xAB'CD'EF; + /// \endcode + int8_t HexMinDigits; + bool operator==(const IntegerLiteralSeparatorStyle &R) const { + return Binary == R.Binary && BinaryMinDigits == R.BinaryMinDigits && + Decimal == R.Decimal && DecimalMinDigits == R.DecimalMinDigits && + Hex == R.Hex && HexMinDigits == R.HexMinDigits; + } + }; + + /// Format integer literal separators (``'`` for C++ and ``_`` for C#, Java, + /// and JavaScript). + /// \version 16 + IntegerLiteralSeparatorStyle IntegerLiteralSeparator; + /// A vector of prefixes ordered by the desired groups for Java imports. /// /// One group's prefix can be a subset of another - the longest prefix is @@ -2246,11 +2918,12 @@ struct FormatStyle { /// /// import org.example.ClassD; /// \endcode + /// \version 8 std::vector<std::string> JavaImportGroups; /// Quotation styles for JavaScript strings. Does not affect template /// strings. - enum JavaScriptQuoteStyle : unsigned char { + enum JavaScriptQuoteStyle : int8_t { /// Leave string quotes as they are. /// \code{.js} /// string1 = "foo"; @@ -2272,6 +2945,7 @@ struct FormatStyle { }; /// The JavaScriptQuoteStyle to use for JavaScript strings. + /// \version 3.9 JavaScriptQuoteStyle JavaScriptQuotes; // clang-format off @@ -2287,9 +2961,14 @@ struct FormatStyle { /// false: /// import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js" /// \endcode + /// \version 3.9 bool JavaScriptWrapImports; // clang-format on + /// Keep empty lines (up to ``MaxEmptyLinesToKeep``) at end of file. + /// \version 17 + bool KeepEmptyLinesAtEOF; + /// If true, the empty line at the start of blocks is kept. /// \code /// true: false: @@ -2298,14 +2977,49 @@ struct FormatStyle { /// bar(); } /// } /// \endcode + /// \version 3.7 bool KeepEmptyLinesAtTheStartOfBlocks; + /// Indentation logic for lambda bodies. + enum LambdaBodyIndentationKind : int8_t { + /// Align lambda body relative to the lambda signature. This is the default. + /// \code + /// someMethod( + /// [](SomeReallyLongLambdaSignatureArgument foo) { + /// return; + /// }); + /// \endcode + LBI_Signature, + /// For statements within block scope, align lambda body relative to the + /// indentation level of the outer scope the lambda signature resides in. + /// \code + /// someMethod( + /// [](SomeReallyLongLambdaSignatureArgument foo) { + /// return; + /// }); + /// + /// someMethod(someOtherMethod( + /// [](SomeReallyLongLambdaSignatureArgument foo) { + /// return; + /// })); + /// \endcode + LBI_OuterScope, + }; + + /// The indentation style of lambda bodies. ``Signature`` (the default) + /// causes the lambda body to be indented one additional level relative to + /// the indentation level of the signature. ``OuterScope`` forces the lambda + /// body to be indented one additional level relative to the parent scope + /// containing the lambda signature. + /// \version 13 + LambdaBodyIndentationKind LambdaBodyIndentation; + /// Supported languages. /// /// When stored in a configuration file, specifies the language, that the /// configuration targets. When passed to the ``reformat()`` function, enables /// syntax features specific to the language. - enum LanguageKind : unsigned char { + enum LanguageKind : int8_t { /// Do not use. LK_None, /// Should be used for C, C++. @@ -2316,6 +3030,8 @@ struct FormatStyle { LK_Java, /// Should be used for JavaScript. LK_JavaScript, + /// Should be used for JSON. + LK_Json, /// Should be used for Objective-C, Objective-C++. LK_ObjC, /// Should be used for Protocol Buffers @@ -2325,14 +3041,42 @@ struct FormatStyle { LK_TableGen, /// Should be used for Protocol Buffer messages in text format /// (https://developers.google.com/protocol-buffers/). - LK_TextProto + LK_TextProto, + /// Should be used for Verilog and SystemVerilog. + /// https://standards.ieee.org/ieee/1800/6700/ + /// https://sci-hub.st/10.1109/IEEESTD.2018.8299595 + LK_Verilog }; bool isCpp() const { return Language == LK_Cpp || Language == LK_ObjC; } bool isCSharp() const { return Language == LK_CSharp; } + bool isJson() const { return Language == LK_Json; } + bool isJavaScript() const { return Language == LK_JavaScript; } + bool isVerilog() const { return Language == LK_Verilog; } + bool isProto() const { + return Language == LK_Proto || Language == LK_TextProto; + } + bool isTableGen() const { return Language == LK_TableGen; } /// Language, this format style is targeted at. + /// \version 3.5 LanguageKind Language; + /// Line ending style. + enum LineEndingStyle : int8_t { + /// Use ``\n``. + LE_LF, + /// Use ``\r\n``. + LE_CRLF, + /// Use ``\n`` unless the input has more lines ending in ``\r\n``. + LE_DeriveLF, + /// Use ``\r\n`` unless the input has more lines ending in ``\n``. + LE_DeriveCRLF, + }; + + /// Line ending style (``\n`` or ``\r\n``) to use. + /// \version 16 + LineEndingStyle LineEnding; + /// A regular expression matching macros that start a block. /// \code /// # With: @@ -2359,11 +3103,53 @@ struct FormatStyle { /// bar(); /// NS_TABLE_FOO_END /// \endcode + /// \version 3.7 std::string MacroBlockBegin; /// A regular expression matching macros that end a block. + /// \version 3.7 std::string MacroBlockEnd; + /// A list of macros of the form \c <definition>=<expansion> . + /// + /// Code will be parsed with macros expanded, in order to determine how to + /// interpret and format the macro arguments. + /// + /// For example, the code: + /// \code + /// A(a*b); + /// \endcode + /// + /// will usually be interpreted as a call to a function A, and the + /// multiplication expression will be formatted as ``a * b``. + /// + /// If we specify the macro definition: + /// \code{.yaml} + /// Macros: + /// - A(x)=x + /// \endcode + /// + /// the code will now be parsed as a declaration of the variable b of type a*, + /// and formatted as ``a* b`` (depending on pointer-binding rules). + /// + /// Features and restrictions: + /// * Both function-like macros and object-like macros are supported. + /// * Macro arguments must be used exactly once in the expansion. + /// * No recursive expansion; macros referencing other macros will be + /// ignored. + /// * Overloading by arity is supported: for example, given the macro + /// definitions A=x, A()=y, A(a)=a + /// + /// \code + /// A; -> x; + /// A(); -> y; + /// A(z); -> z; + /// A(a, b); // will not be expanded. + /// \endcode + /// + /// \version 17 + std::vector<std::string> Macros; + /// The maximum number of consecutive empty lines to keep. /// \code /// MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0 @@ -2375,10 +3161,11 @@ struct FormatStyle { /// return i; /// } /// \endcode + /// \version 3.7 unsigned MaxEmptyLinesToKeep; /// Different ways to indent namespace contents. - enum NamespaceIndentationKind : unsigned char { + enum NamespaceIndentationKind : int8_t { /// Don't indent in namespaces. /// \code /// namespace out { @@ -2412,8 +3199,22 @@ struct FormatStyle { }; /// The indentation used for namespaces. + /// \version 3.7 NamespaceIndentationKind NamespaceIndentation; + /// A vector of macros which are used to open namespace blocks. + /// + /// These are expected to be macros of the form: + /// \code + /// NAMESPACE(<namespace-name>, ...) { + /// <namespace-content> + /// } + /// \endcode + /// + /// For example: TESTSUITE + /// \version 9 + std::vector<std::string> NamespaceMacros; + /// Controls bin-packing Objective-C protocol conformance list /// items into as few lines as possible when they go over ``ColumnLimit``. /// @@ -2444,6 +3245,7 @@ struct FormatStyle { /// ddddddddddddd> { /// } /// \endcode + /// \version 7 BinPackStyle ObjCBinPackProtocolList; /// The number of characters to use for indentation of ObjC blocks. @@ -2454,12 +3256,9 @@ struct FormatStyle { /// [self onOperationDone]; /// }]; /// \endcode + /// \version 3.7 unsigned ObjCBlockIndentWidth; - /// Add a space after ``@property`` in Objective-C, i.e. use - /// ``@property (readonly)`` instead of ``@property(readonly)``. - bool ObjCSpaceAfterProperty; - /// Break parameters list into lines when there is nested block /// parameters in a function call. /// \code @@ -2481,43 +3280,151 @@ struct FormatStyle { /// }] /// } /// \endcode + /// \version 11 bool ObjCBreakBeforeNestedBlockParam; + /// The order in which ObjC property attributes should appear. + /// + /// Attributes in code will be sorted in the order specified. Any attributes + /// encountered that are not mentioned in this array will be sorted last, in + /// stable order. Comments between attributes will leave the attributes + /// untouched. + /// \warning + /// Using this option could lead to incorrect code formatting due to + /// clang-format's lack of complete semantic information. As such, extra + /// care should be taken to review code changes made by this option. + /// \endwarning + /// \code{.yaml} + /// ObjCPropertyAttributeOrder: [ + /// class, direct, + /// atomic, nonatomic, + /// assign, retain, strong, copy, weak, unsafe_unretained, + /// readonly, readwrite, getter, setter, + /// nullable, nonnull, null_resettable, null_unspecified + /// ] + /// \endcode + /// \version 18 + std::vector<std::string> ObjCPropertyAttributeOrder; + + /// Add a space after ``@property`` in Objective-C, i.e. use + /// ``@property (readonly)`` instead of ``@property(readonly)``. + /// \version 3.7 + bool ObjCSpaceAfterProperty; + /// Add a space in front of an Objective-C protocol list, i.e. use /// ``Foo <Protocol>`` instead of ``Foo<Protocol>``. + /// \version 3.7 bool ObjCSpaceBeforeProtocolList; + /// Different ways to try to fit all constructor initializers on a line. + enum PackConstructorInitializersStyle : int8_t { + /// Always put each constructor initializer on its own line. + /// \code + /// Constructor() + /// : a(), + /// b() + /// \endcode + PCIS_Never, + /// Bin-pack constructor initializers. + /// \code + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), + /// cccccccccccccccccccc() + /// \endcode + PCIS_BinPack, + /// Put all constructor initializers on the current line if they fit. + /// Otherwise, put each one on its own line. + /// \code + /// Constructor() : a(), b() + /// + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), + /// bbbbbbbbbbbbbbbbbbbb(), + /// ddddddddddddd() + /// \endcode + PCIS_CurrentLine, + /// Same as ``PCIS_CurrentLine`` except that if all constructor initializers + /// do not fit on the current line, try to fit them on the next line. + /// \code + /// Constructor() : a(), b() + /// + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd() + /// + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), + /// bbbbbbbbbbbbbbbbbbbb(), + /// cccccccccccccccccccc() + /// \endcode + PCIS_NextLine, + /// Put all constructor initializers on the next line if they fit. + /// Otherwise, put each one on its own line. + /// \code + /// Constructor() + /// : a(), b() + /// + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd() + /// + /// Constructor() + /// : aaaaaaaaaaaaaaaaaaaa(), + /// bbbbbbbbbbbbbbbbbbbb(), + /// cccccccccccccccccccc() + /// \endcode + PCIS_NextLineOnly, + }; + + /// The pack constructor initializers style to use. + /// \version 14 + PackConstructorInitializersStyle PackConstructorInitializers; + /// The penalty for breaking around an assignment operator. + /// \version 5 unsigned PenaltyBreakAssignment; /// The penalty for breaking a function call after ``call(``. + /// \version 3.7 unsigned PenaltyBreakBeforeFirstCallParameter; /// The penalty for each line break introduced inside a comment. + /// \version 3.7 unsigned PenaltyBreakComment; /// The penalty for breaking before the first ``<<``. + /// \version 3.7 unsigned PenaltyBreakFirstLessLess; + /// The penalty for breaking after ``(``. + /// \version 14 + unsigned PenaltyBreakOpenParenthesis; + + /// The penalty for breaking after ``::``. + /// \version 18 + unsigned PenaltyBreakScopeResolution; + /// The penalty for each line break introduced inside a string literal. + /// \version 3.7 unsigned PenaltyBreakString; /// The penalty for breaking after template declaration. + /// \version 7 unsigned PenaltyBreakTemplateDeclaration; /// The penalty for each character outside of the column limit. + /// \version 3.7 unsigned PenaltyExcessCharacter; - /// Penalty for putting the return type of a function onto its own - /// line. - unsigned PenaltyReturnTypeOnItsOwnLine; - /// Penalty for each character of whitespace indentation /// (counted relative to leading non-whitespace column). + /// \version 12 unsigned PenaltyIndentedWhitespace; - /// The ``&`` and ``*`` alignment style. - enum PointerAlignmentStyle : unsigned char { + /// Penalty for putting the return type of a function onto its own line. + /// \version 3.7 + unsigned PenaltyReturnTypeOnItsOwnLine; + + /// The ``&``, ``&&`` and ``*`` alignment style. + enum PointerAlignmentStyle : int8_t { /// Align pointer to the left. /// \code /// int* a; @@ -2536,8 +3443,96 @@ struct FormatStyle { }; /// Pointer and reference alignment style. + /// \version 3.7 PointerAlignmentStyle PointerAlignment; + /// The number of columns to use for indentation of preprocessor statements. + /// When set to -1 (default) ``IndentWidth`` is used also for preprocessor + /// statements. + /// \code + /// PPIndentWidth: 1 + /// + /// #ifdef __linux__ + /// # define FOO + /// #else + /// # define BAR + /// #endif + /// \endcode + /// \version 13 + int PPIndentWidth; + + /// Different specifiers and qualifiers alignment styles. + enum QualifierAlignmentStyle : int8_t { + /// Don't change specifiers/qualifiers to either Left or Right alignment + /// (default). + /// \code + /// int const a; + /// const int *a; + /// \endcode + QAS_Leave, + /// Change specifiers/qualifiers to be left-aligned. + /// \code + /// const int a; + /// const int *a; + /// \endcode + QAS_Left, + /// Change specifiers/qualifiers to be right-aligned. + /// \code + /// int const a; + /// int const *a; + /// \endcode + QAS_Right, + /// Change specifiers/qualifiers to be aligned based on ``QualifierOrder``. + /// With: + /// \code{.yaml} + /// QualifierOrder: ['inline', 'static', 'type', 'const'] + /// \endcode + /// + /// \code + /// + /// int const a; + /// int const *a; + /// \endcode + QAS_Custom + }; + + /// Different ways to arrange specifiers and qualifiers (e.g. const/volatile). + /// \warning + /// Setting ``QualifierAlignment`` to something other than ``Leave``, COULD + /// lead to incorrect code formatting due to incorrect decisions made due to + /// clang-formats lack of complete semantic information. + /// As such extra care should be taken to review code changes made by the use + /// of this option. + /// \endwarning + /// \version 14 + QualifierAlignmentStyle QualifierAlignment; + + /// The order in which the qualifiers appear. + /// Order is an array that can contain any of the following: + /// + /// * const + /// * inline + /// * static + /// * friend + /// * constexpr + /// * volatile + /// * restrict + /// * type + /// + /// \note + /// it MUST contain 'type'. + /// \endnote + /// + /// Items to the left of 'type' will be placed to the left of the type and + /// aligned in the order supplied. Items to the right of 'type' will be + /// placed to the right of the type and aligned in the order supplied. + /// + /// \code{.yaml} + /// QualifierOrder: ['inline', 'static', 'type', 'const', 'volatile' ] + /// \endcode + /// \version 14 + std::vector<std::string> QualifierOrder; + /// See documentation of ``RawStringFormats``. struct RawStringFormat { /// The language of this raw string. @@ -2595,10 +3590,39 @@ struct FormatStyle { /// BasedOnStyle: llvm /// CanonicalDelimiter: 'cc' /// \endcode + /// \version 6 std::vector<RawStringFormat> RawStringFormats; + /// \brief The ``&`` and ``&&`` alignment style. + enum ReferenceAlignmentStyle : int8_t { + /// Align reference like ``PointerAlignment``. + RAS_Pointer, + /// Align reference to the left. + /// \code + /// int& a; + /// \endcode + RAS_Left, + /// Align reference to the right. + /// \code + /// int &a; + /// \endcode + RAS_Right, + /// Align reference in the middle. + /// \code + /// int & a; + /// \endcode + RAS_Middle + }; + + /// \brief Reference alignment style (overrides ``PointerAlignment`` for + /// references). + /// \version 13 + ReferenceAlignmentStyle ReferenceAlignment; + // clang-format off - /// If ``true``, clang-format will attempt to re-flow comments. + /// If ``true``, clang-format will attempt to re-flow comments. That is it + /// will touch a comment and *reflow* long comments into new lines, trying to + /// obey the ``ColumnLimit``. /// \code /// false: /// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information @@ -2610,19 +3634,345 @@ struct FormatStyle { /// /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of /// * information */ /// \endcode + /// \version 3.8 bool ReflowComments; // clang-format on - /// If ``true``, clang-format will sort ``#includes``. + /// Remove optional braces of control statements (``if``, ``else``, ``for``, + /// and ``while``) in C++ according to the LLVM coding style. + /// \warning + /// This option will be renamed and expanded to support other styles. + /// \endwarning + /// \warning + /// Setting this option to ``true`` could lead to incorrect code formatting + /// due to clang-format's lack of complete semantic information. As such, + /// extra care should be taken to review code changes made by this option. + /// \endwarning /// \code - /// false: true: - /// #include "b.h" vs. #include "a.h" - /// #include "a.h" #include "b.h" + /// false: true: + /// + /// if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D)) + /// handleFunctionDecl(D); handleFunctionDecl(D); + /// } else if (isa<VarDecl>(D)) { else if (isa<VarDecl>(D)) + /// handleVarDecl(D); handleVarDecl(D); + /// } + /// + /// if (isa<VarDecl>(D)) { vs. if (isa<VarDecl>(D)) { + /// for (auto *A : D.attrs()) { for (auto *A : D.attrs()) + /// if (shouldProcessAttr(A)) { if (shouldProcessAttr(A)) + /// handleAttr(A); handleAttr(A); + /// } } + /// } + /// } + /// + /// if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D)) + /// for (auto *A : D.attrs()) { for (auto *A : D.attrs()) + /// handleAttr(A); handleAttr(A); + /// } + /// } + /// + /// if (auto *D = (T)(D)) { vs. if (auto *D = (T)(D)) { + /// if (shouldProcess(D)) { if (shouldProcess(D)) + /// handleVarDecl(D); handleVarDecl(D); + /// } else { else + /// markAsIgnored(D); markAsIgnored(D); + /// } } + /// } + /// + /// if (a) { vs. if (a) + /// b(); b(); + /// } else { else if (c) + /// if (c) { d(); + /// d(); else + /// } else { e(); + /// e(); + /// } + /// } + /// \endcode + /// \version 14 + bool RemoveBracesLLVM; + + /// Types of redundant parentheses to remove. + enum RemoveParenthesesStyle : int8_t { + /// Do not remove parentheses. + /// \code + /// class __declspec((dllimport)) X {}; + /// co_return (((0))); + /// return ((a + b) - ((c + d))); + /// \endcode + RPS_Leave, + /// Replace multiple parentheses with single parentheses. + /// \code + /// class __declspec(dllimport) X {}; + /// co_return (0); + /// return ((a + b) - (c + d)); + /// \endcode + RPS_MultipleParentheses, + /// Also remove parentheses enclosing the expression in a + /// ``return``/``co_return`` statement. + /// \code + /// class __declspec(dllimport) X {}; + /// co_return 0; + /// return (a + b) - (c + d); + /// \endcode + RPS_ReturnStatement, + }; + + /// Remove redundant parentheses. + /// \warning + /// Setting this option to any value other than ``Leave`` could lead to + /// incorrect code formatting due to clang-format's lack of complete semantic + /// information. As such, extra care should be taken to review code changes + /// made by this option. + /// \endwarning + /// \version 17 + RemoveParenthesesStyle RemoveParentheses; + + /// Remove semicolons after the closing brace of a non-empty function. + /// \warning + /// Setting this option to ``true`` could lead to incorrect code formatting + /// due to clang-format's lack of complete semantic information. As such, + /// extra care should be taken to review code changes made by this option. + /// \endwarning + /// \code + /// false: true: + /// + /// int max(int a, int b) { int max(int a, int b) { + /// return a > b ? a : b; return a > b ? a : b; + /// }; } + /// + /// \endcode + /// \version 16 + bool RemoveSemicolon; + + /// \brief The possible positions for the requires clause. The + /// ``IndentRequires`` option is only used if the ``requires`` is put on the + /// start of a line. + enum RequiresClausePositionStyle : int8_t { + /// Always put the ``requires`` clause on its own line. + /// \code + /// template <typename T> + /// requires C<T> + /// struct Foo {... + /// + /// template <typename T> + /// requires C<T> + /// void bar(T t) {... + /// + /// template <typename T> + /// void baz(T t) + /// requires C<T> + /// {... + /// \endcode + RCPS_OwnLine, + /// Try to put the clause together with the preceding part of a declaration. + /// For class templates: stick to the template declaration. + /// For function templates: stick to the template declaration. + /// For function declaration followed by a requires clause: stick to the + /// parameter list. + /// \code + /// template <typename T> requires C<T> + /// struct Foo {... + /// + /// template <typename T> requires C<T> + /// void bar(T t) {... + /// + /// template <typename T> + /// void baz(T t) requires C<T> + /// {... + /// \endcode + RCPS_WithPreceding, + /// Try to put the ``requires`` clause together with the class or function + /// declaration. + /// \code + /// template <typename T> + /// requires C<T> struct Foo {... + /// + /// template <typename T> + /// requires C<T> void bar(T t) {... + /// + /// template <typename T> + /// void baz(T t) + /// requires C<T> {... + /// \endcode + RCPS_WithFollowing, + /// Try to put everything in the same line if possible. Otherwise normal + /// line breaking rules take over. + /// \code + /// // Fitting: + /// template <typename T> requires C<T> struct Foo {... + /// + /// template <typename T> requires C<T> void bar(T t) {... + /// + /// template <typename T> void bar(T t) requires C<T> {... + /// + /// // Not fitting, one possible example: + /// template <typename LongName> + /// requires C<LongName> + /// struct Foo {... + /// + /// template <typename LongName> + /// requires C<LongName> + /// void bar(LongName ln) { + /// + /// template <typename LongName> + /// void bar(LongName ln) + /// requires C<LongName> { + /// \endcode + RCPS_SingleLine, + }; + + /// \brief The position of the ``requires`` clause. + /// \version 15 + RequiresClausePositionStyle RequiresClausePosition; + + /// Indentation logic for requires expression bodies. + enum RequiresExpressionIndentationKind : int8_t { + /// Align requires expression body relative to the indentation level of the + /// outer scope the requires expression resides in. + /// This is the default. + /// \code + /// template <typename T> + /// concept C = requires(T t) { + /// ... + /// } + /// \endcode + REI_OuterScope, + /// Align requires expression body relative to the ``requires`` keyword. + /// \code + /// template <typename T> + /// concept C = requires(T t) { + /// ... + /// } + /// \endcode + REI_Keyword, + }; + + /// The indentation used for requires expression bodies. + /// \version 16 + RequiresExpressionIndentationKind RequiresExpressionIndentation; + + /// \brief The style if definition blocks should be separated. + enum SeparateDefinitionStyle : int8_t { + /// Leave definition blocks as they are. + SDS_Leave, + /// Insert an empty line between definition blocks. + SDS_Always, + /// Remove any empty line between definition blocks. + SDS_Never + }; + + /// Specifies the use of empty lines to separate definition blocks, including + /// classes, structs, enums, and functions. + /// \code + /// Never v.s. Always + /// #include <cstring> #include <cstring> + /// struct Foo { + /// int a, b, c; struct Foo { + /// }; int a, b, c; + /// namespace Ns { }; + /// class Bar { + /// public: namespace Ns { + /// struct Foobar { class Bar { + /// int a; public: + /// int b; struct Foobar { + /// }; int a; + /// private: int b; + /// int t; }; + /// int method1() { + /// // ... private: + /// } int t; + /// enum List { + /// ITEM1, int method1() { + /// ITEM2 // ... + /// }; } + /// template<typename T> + /// int method2(T x) { enum List { + /// // ... ITEM1, + /// } ITEM2 + /// int i, j, k; }; + /// int method3(int par) { + /// // ... template<typename T> + /// } int method2(T x) { + /// }; // ... + /// class C {}; } + /// } + /// int i, j, k; + /// + /// int method3(int par) { + /// // ... + /// } + /// }; + /// + /// class C {}; + /// } + /// \endcode + /// \version 14 + SeparateDefinitionStyle SeparateDefinitionBlocks; + + /// The maximal number of unwrapped lines that a short namespace spans. + /// Defaults to 1. + /// + /// This determines the maximum length of short namespaces by counting + /// unwrapped lines (i.e. containing neither opening nor closing + /// namespace brace) and makes "FixNamespaceComments" omit adding + /// end comments for those. + /// \code + /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 + /// namespace a { namespace a { + /// int foo; int foo; + /// } } // namespace a + /// + /// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0 + /// namespace b { namespace b { + /// int foo; int foo; + /// int bar; int bar; + /// } // namespace b } // namespace b /// \endcode - bool SortIncludes; + /// \version 13 + unsigned ShortNamespaceLines; + + /// Do not format macro definition body. + /// \version 18 + bool SkipMacroDefinitionBody; + + /// Include sorting options. + enum SortIncludesOptions : int8_t { + /// Includes are never sorted. + /// \code + /// #include "B/A.h" + /// #include "A/B.h" + /// #include "a/b.h" + /// #include "A/b.h" + /// #include "B/a.h" + /// \endcode + SI_Never, + /// Includes are sorted in an ASCIIbetical or case sensitive fashion. + /// \code + /// #include "A/B.h" + /// #include "A/b.h" + /// #include "B/A.h" + /// #include "B/a.h" + /// #include "a/b.h" + /// \endcode + SI_CaseSensitive, + /// Includes are sorted in an alphabetical or case insensitive fashion. + /// \code + /// #include "A/B.h" + /// #include "A/b.h" + /// #include "a/b.h" + /// #include "B/A.h" + /// #include "B/a.h" + /// \endcode + SI_CaseInsensitive, + }; + + /// Controls if and how clang-format will sort ``#includes``. + /// \version 3.8 + SortIncludesOptions SortIncludes; /// Position for Java Static imports. - enum SortJavaStaticImportOptions : unsigned char { + enum SortJavaStaticImportOptions : int8_t { /// Static imports are placed before non-static imports. /// \code{.java} /// import static org.example.function1; @@ -2642,29 +3992,59 @@ struct FormatStyle { /// When sorting Java imports, by default static imports are placed before /// non-static imports. If ``JavaStaticImportAfterImport`` is ``After``, /// static imports are placed after non-static imports. + /// \version 12 SortJavaStaticImportOptions SortJavaStaticImport; - /// If ``true``, clang-format will sort using declarations. - /// - /// The order of using declarations is defined as follows: - /// Split the strings by "::" and discard any initial empty strings. The last - /// element of each list is a non-namespace name; all others are namespace - /// names. Sort the lists of names lexicographically, where the sort order of - /// individual names is that all non-namespace names come before all namespace - /// names, and within those groups, names are in case-insensitive - /// lexicographic order. - /// \code - /// false: true: - /// using std::cout; vs. using std::cin; - /// using std::cin; using std::cout; - /// \endcode - bool SortUsingDeclarations; + /// Using declaration sorting options. + enum SortUsingDeclarationsOptions : int8_t { + /// Using declarations are never sorted. + /// \code + /// using std::chrono::duration_cast; + /// using std::move; + /// using boost::regex; + /// using boost::regex_constants::icase; + /// using std::string; + /// \endcode + SUD_Never, + /// Using declarations are sorted in the order defined as follows: + /// Split the strings by "::" and discard any initial empty strings. Sort + /// the lists of names lexicographically, and within those groups, names are + /// in case-insensitive lexicographic order. + /// \code + /// using boost::regex; + /// using boost::regex_constants::icase; + /// using std::chrono::duration_cast; + /// using std::move; + /// using std::string; + /// \endcode + SUD_Lexicographic, + /// Using declarations are sorted in the order defined as follows: + /// Split the strings by "::" and discard any initial empty strings. The + /// last element of each list is a non-namespace name; all others are + /// namespace names. Sort the lists of names lexicographically, where the + /// sort order of individual names is that all non-namespace names come + /// before all namespace names, and within those groups, names are in + /// case-insensitive lexicographic order. + /// \code + /// using boost::regex; + /// using boost::regex_constants::icase; + /// using std::move; + /// using std::string; + /// using std::chrono::duration_cast; + /// \endcode + SUD_LexicographicNumeric, + }; + + /// Controls if and how clang-format will sort using declarations. + /// \version 5 + SortUsingDeclarationsOptions SortUsingDeclarations; /// If ``true``, a space is inserted after C style casts. /// \code /// true: false: /// (int) i; vs. (int)i; /// \endcode + /// \version 3.5 bool SpaceAfterCStyleCast; /// If ``true``, a space is inserted after the logical not operator (``!``). @@ -2672,6 +4052,7 @@ struct FormatStyle { /// true: false: /// ! someExpression(); vs. !someExpression(); /// \endcode + /// \version 9 bool SpaceAfterLogicalNot; /// If \c true, a space will be inserted after the 'template' keyword. @@ -2679,10 +4060,11 @@ struct FormatStyle { /// true: false: /// template <int> void foo(); vs. template<int> void foo(); /// \endcode + /// \version 4 bool SpaceAfterTemplateKeyword; /// Different ways to put a space before opening parentheses. - enum SpaceAroundPointerQualifiersStyle : unsigned char { + enum SpaceAroundPointerQualifiersStyle : int8_t { /// Don't ensure spaces around pointer qualifiers and use PointerAlignment /// instead. /// \code @@ -2711,6 +4093,7 @@ struct FormatStyle { }; /// Defines in which cases to put a space before or after pointer qualifiers + /// \version 12 SpaceAroundPointerQualifiersStyle SpaceAroundPointerQualifiers; /// If ``false``, spaces will be removed before assignment operators. @@ -2719,6 +4102,7 @@ struct FormatStyle { /// int a = 5; vs. int a= 5; /// a += 42; a+= 42; /// \endcode + /// \version 3.7 bool SpaceBeforeAssignmentOperators; /// If ``false``, spaces will be removed before case colon. @@ -2728,6 +4112,7 @@ struct FormatStyle { /// case 1 : break; case 1: break; /// } } /// \endcode + /// \version 12 bool SpaceBeforeCaseColon; /// If ``true``, a space will be inserted before a C++11 braced list @@ -2739,6 +4124,7 @@ struct FormatStyle { /// vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 }; /// new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 }; /// \endcode + /// \version 7 bool SpaceBeforeCpp11BracedList; /// If ``false``, spaces will be removed before constructor initializer @@ -2747,6 +4133,7 @@ struct FormatStyle { /// true: false: /// Foo::Foo() : a(a) {} Foo::Foo(): a(a) {} /// \endcode + /// \version 7 bool SpaceBeforeCtorInitializerColon; /// If ``false``, spaces will be removed before inheritance colon. @@ -2754,18 +4141,25 @@ struct FormatStyle { /// true: false: /// class Foo : Bar {} vs. class Foo: Bar {} /// \endcode + /// \version 7 bool SpaceBeforeInheritanceColon; + /// If ``true``, a space will be added before a JSON colon. For other + /// languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead. + /// \code + /// true: false: + /// { { + /// "key" : "value" vs. "key": "value" + /// } } + /// \endcode + /// \version 17 + bool SpaceBeforeJsonColon; + /// Different ways to put a space before opening parentheses. - enum SpaceBeforeParensOptions : unsigned char { - /// Never put a space before opening parentheses. - /// \code - /// void f() { - /// if(true) { - /// f(); - /// } - /// } - /// \endcode + enum SpaceBeforeParensStyle : int8_t { + /// This is **deprecated** and replaced by ``Custom`` below, with all + /// ``SpaceBeforeParensOptions`` but ``AfterPlacementOperator`` set to + /// ``false``. SBPO_Never, /// Put a space before opening parentheses only after control statement /// keywords (``for/if/while...``). @@ -2778,8 +4172,10 @@ struct FormatStyle { /// \endcode SBPO_ControlStatements, /// Same as ``SBPO_ControlStatements`` except this option doesn't apply to - /// ForEach macros. This is useful in projects where ForEach macros are - /// treated as function calls instead of control statements. + /// ForEach and If macros. This is useful in projects where ForEach/If + /// macros are treated as function calls instead of control statements. + /// ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for + /// backward compatibility. /// \code /// void f() { /// Q_FOREACH(...) { @@ -2787,7 +4183,7 @@ struct FormatStyle { /// } /// } /// \endcode - SBPO_ControlStatementsExceptForEachMacros, + SBPO_ControlStatementsExceptControlMacros, /// Put a space before opening parentheses only if the parentheses are not /// empty i.e. '()' /// \code @@ -2810,11 +4206,151 @@ struct FormatStyle { /// } /// } /// \endcode - SBPO_Always + SBPO_Always, + /// Configure each individual space before parentheses in + /// ``SpaceBeforeParensOptions``. + SBPO_Custom, }; /// Defines in which cases to put a space before opening parentheses. - SpaceBeforeParensOptions SpaceBeforeParens; + /// \version 3.5 + SpaceBeforeParensStyle SpaceBeforeParens; + + /// Precise control over the spacing before parentheses. + /// \code + /// # Should be declared this way: + /// SpaceBeforeParens: Custom + /// SpaceBeforeParensOptions: + /// AfterControlStatements: true + /// AfterFunctionDefinitionName: true + /// \endcode + struct SpaceBeforeParensCustom { + /// If ``true``, put space between control statement keywords + /// (for/if/while...) and opening parentheses. + /// \code + /// true: false: + /// if (...) {} vs. if(...) {} + /// \endcode + bool AfterControlStatements; + /// If ``true``, put space between foreach macros and opening parentheses. + /// \code + /// true: false: + /// FOREACH (...) vs. FOREACH(...) + /// <loop-body> <loop-body> + /// \endcode + bool AfterForeachMacros; + /// If ``true``, put a space between function declaration name and opening + /// parentheses. + /// \code + /// true: false: + /// void f (); vs. void f(); + /// \endcode + bool AfterFunctionDeclarationName; + /// If ``true``, put a space between function definition name and opening + /// parentheses. + /// \code + /// true: false: + /// void f () {} vs. void f() {} + /// \endcode + bool AfterFunctionDefinitionName; + /// If ``true``, put space between if macros and opening parentheses. + /// \code + /// true: false: + /// IF (...) vs. IF(...) + /// <conditional-body> <conditional-body> + /// \endcode + bool AfterIfMacros; + /// If ``true``, put a space between operator overloading and opening + /// parentheses. + /// \code + /// true: false: + /// void operator++ (int a); vs. void operator++(int a); + /// object.operator++ (10); object.operator++(10); + /// \endcode + bool AfterOverloadedOperator; + /// If ``true``, put a space between operator ``new``/``delete`` and opening + /// parenthesis. + /// \code + /// true: false: + /// new (buf) T; vs. new(buf) T; + /// delete (buf) T; delete(buf) T; + /// \endcode + bool AfterPlacementOperator; + /// If ``true``, put space between requires keyword in a requires clause and + /// opening parentheses, if there is one. + /// \code + /// true: false: + /// template<typename T> vs. template<typename T> + /// requires (A<T> && B<T>) requires(A<T> && B<T>) + /// ... ... + /// \endcode + bool AfterRequiresInClause; + /// If ``true``, put space between requires keyword in a requires expression + /// and opening parentheses. + /// \code + /// true: false: + /// template<typename T> vs. template<typename T> + /// concept C = requires (T t) { concept C = requires(T t) { + /// ... ... + /// } } + /// \endcode + bool AfterRequiresInExpression; + /// If ``true``, put a space before opening parentheses only if the + /// parentheses are not empty. + /// \code + /// true: false: + /// void f (int a); vs. void f(); + /// f (a); f(); + /// \endcode + bool BeforeNonEmptyParentheses; + + SpaceBeforeParensCustom() + : AfterControlStatements(false), AfterForeachMacros(false), + AfterFunctionDeclarationName(false), + AfterFunctionDefinitionName(false), AfterIfMacros(false), + AfterOverloadedOperator(false), AfterPlacementOperator(true), + AfterRequiresInClause(false), AfterRequiresInExpression(false), + BeforeNonEmptyParentheses(false) {} + + bool operator==(const SpaceBeforeParensCustom &Other) const { + return AfterControlStatements == Other.AfterControlStatements && + AfterForeachMacros == Other.AfterForeachMacros && + AfterFunctionDeclarationName == + Other.AfterFunctionDeclarationName && + AfterFunctionDefinitionName == Other.AfterFunctionDefinitionName && + AfterIfMacros == Other.AfterIfMacros && + AfterOverloadedOperator == Other.AfterOverloadedOperator && + AfterPlacementOperator == Other.AfterPlacementOperator && + AfterRequiresInClause == Other.AfterRequiresInClause && + AfterRequiresInExpression == Other.AfterRequiresInExpression && + BeforeNonEmptyParentheses == Other.BeforeNonEmptyParentheses; + } + }; + + /// Control of individual space before parentheses. + /// + /// If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify + /// how each individual space before parentheses case should be handled. + /// Otherwise, this is ignored. + /// \code{.yaml} + /// # Example of usage: + /// SpaceBeforeParens: Custom + /// SpaceBeforeParensOptions: + /// AfterControlStatements: true + /// AfterFunctionDefinitionName: true + /// \endcode + /// \version 14 + SpaceBeforeParensCustom SpaceBeforeParensOptions; + + /// If ``true``, spaces will be before ``[``. + /// Lambdas will not be affected. Only the first ``[`` will get a space added. + /// \code + /// true: false: + /// int a [5]; vs. int a[5]; + /// int a [5][5]; vs. int a[5][5]; + /// \endcode + /// \version 10 + bool SpaceBeforeSquareBrackets; /// If ``false``, spaces will be removed before range-based for loop /// colon. @@ -2822,6 +4358,7 @@ struct FormatStyle { /// true: false: /// for (auto v : values) {} vs. for(auto v: values) {} /// \endcode + /// \version 7 bool SpaceBeforeRangeBasedForLoopColon; /// If ``true``, spaces will be inserted into ``{}``. @@ -2830,26 +4367,24 @@ struct FormatStyle { /// void f() { } vs. void f() {} /// while (true) { } while (true) {} /// \endcode + /// \version 10 bool SpaceInEmptyBlock; /// If ``true``, spaces may be inserted into ``()``. - /// \code - /// true: false: - /// void f( ) { vs. void f() { - /// int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; - /// if (true) { if (true) { - /// f( ); f(); - /// } } - /// } } - /// \endcode - bool SpaceInEmptyParentheses; + /// This option is **deprecated**. See ``InEmptyParentheses`` of + /// ``SpacesInParensOptions``. + /// \version 3.7 + // bool SpaceInEmptyParentheses; /// The number of spaces before trailing line comments /// (``//`` - comments). /// - /// This does not affect trailing block comments (``/*`` - comments) as - /// those commonly have different usage patterns and a number of special - /// cases. + /// This does not affect trailing block comments (``/*`` - comments) as those + /// commonly have different usage patterns and a number of special cases. In + /// the case of Verilog, it doesn't affect a comment right after the opening + /// parenthesis in the port or parameter list in a module header, because it + /// is probably for the port on the following line instead of the parenthesis + /// it follows. /// \code /// SpacesBeforeTrailingComments: 3 /// void f() { @@ -2858,95 +4393,213 @@ struct FormatStyle { /// } // foo /// } /// \endcode + /// \version 3.7 unsigned SpacesBeforeTrailingComments; - /// If ``true``, spaces will be inserted after ``<`` and before ``>`` - /// in template argument lists. - /// \code - /// true: false: - /// static_cast< int >(arg); vs. static_cast<int>(arg); - /// std::function< void(int) > fct; std::function<void(int)> fct; - /// \endcode - bool SpacesInAngles; + /// Styles for adding spacing after ``<`` and before ``>`` + /// in template argument lists. + enum SpacesInAnglesStyle : int8_t { + /// Remove spaces after ``<`` and before ``>``. + /// \code + /// static_cast<int>(arg); + /// std::function<void(int)> fct; + /// \endcode + SIAS_Never, + /// Add spaces after ``<`` and before ``>``. + /// \code + /// static_cast< int >(arg); + /// std::function< void(int) > fct; + /// \endcode + SIAS_Always, + /// Keep a single space after ``<`` and before ``>`` if any spaces were + /// present. Option ``Standard: Cpp03`` takes precedence. + SIAS_Leave + }; + /// The SpacesInAnglesStyle to use for template argument lists. + /// \version 3.4 + SpacesInAnglesStyle SpacesInAngles; /// If ``true``, spaces will be inserted around if/for/switch/while /// conditions. - /// \code - /// true: false: - /// if ( a ) { ... } vs. if (a) { ... } - /// while ( i < 5 ) { ... } while (i < 5) { ... } - /// \endcode - bool SpacesInConditionalStatement; - - /// If ``true``, spaces are inserted inside container literals (e.g. - /// ObjC and Javascript array and dict literals). + /// This option is **deprecated**. See ``InConditionalStatements`` of + /// ``SpacesInParensOptions``. + /// \version 10 + // bool SpacesInConditionalStatement; + + /// If ``true``, spaces are inserted inside container literals (e.g. ObjC and + /// Javascript array and dict literals). For JSON, use + /// ``SpaceBeforeJsonColon`` instead. /// \code{.js} /// true: false: /// var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3]; /// f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3}); /// \endcode + /// \version 3.7 bool SpacesInContainerLiterals; /// If ``true``, spaces may be inserted into C style casts. - /// \code - /// true: false: - /// x = ( int32 )y vs. x = (int32)y - /// \endcode - bool SpacesInCStyleCastParentheses; + /// This option is **deprecated**. See ``InCStyleCasts`` of + /// ``SpacesInParensOptions``. + /// \version 3.7 + // bool SpacesInCStyleCastParentheses; + + /// Control of spaces within a single line comment. + struct SpacesInLineComment { + /// The minimum number of spaces at the start of the comment. + unsigned Minimum; + /// The maximum number of spaces at the start of the comment. + unsigned Maximum; + }; - /// If ``true``, spaces will be inserted after ``(`` and before ``)``. + /// How many spaces are allowed at the start of a line comment. To disable the + /// maximum set it to ``-1``, apart from that the maximum takes precedence + /// over the minimum. /// \code - /// true: false: - /// t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; + /// Minimum = 1 + /// Maximum = -1 + /// // One space is forced + /// + /// // but more spaces are possible + /// + /// Minimum = 0 + /// Maximum = 0 + /// //Forces to start every comment directly after the slashes /// \endcode - bool SpacesInParentheses; - - /// If ``true``, spaces will be inserted after ``[`` and before ``]``. - /// Lambdas without arguments or unspecified size array declarations will not - /// be affected. + /// + /// Note that in line comment sections the relative indent of the subsequent + /// lines is kept, that means the following: /// \code - /// true: false: - /// int a[ 5 ]; vs. int a[5]; - /// std::unique_ptr<int[]> foo() {} // Won't be affected + /// before: after: + /// Minimum: 1 + /// //if (b) { // if (b) { + /// // return true; // return true; + /// //} // } + /// + /// Maximum: 0 + /// /// List: ///List: + /// /// - Foo /// - Foo + /// /// - Bar /// - Bar /// \endcode - bool SpacesInSquareBrackets; + /// + /// This option has only effect if ``ReflowComments`` is set to ``true``. + /// \version 13 + SpacesInLineComment SpacesInLineCommentPrefix; - /// If ``true``, spaces will be before ``[``. - /// Lambdas will not be affected. Only the first ``[`` will get a space added. + /// Different ways to put a space before opening and closing parentheses. + enum SpacesInParensStyle : int8_t { + /// Never put a space in parentheses. + /// \code + /// void f() { + /// if(true) { + /// f(); + /// } + /// } + /// \endcode + SIPO_Never, + /// Configure each individual space in parentheses in + /// `SpacesInParensOptions`. + SIPO_Custom, + }; + + /// If ``true``, spaces will be inserted after ``(`` and before ``)``. + /// This option is **deprecated**. The previous behavior is preserved by using + /// ``SpacesInParens`` with ``Custom`` and by setting all + /// ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and + /// ``InEmptyParentheses``. + /// \version 3.7 + // bool SpacesInParentheses; + + /// Defines in which cases spaces will be inserted after ``(`` and before + /// ``)``. + /// \version 17 + SpacesInParensStyle SpacesInParens; + + /// Precise control over the spacing in parentheses. /// \code - /// true: false: - /// int a [5]; vs. int a[5]; - /// int a [5][5]; vs. int a[5][5]; + /// # Should be declared this way: + /// SpacesInParens: Custom + /// SpacesInParensOptions: + /// InConditionalStatements: true + /// Other: true /// \endcode - bool SpaceBeforeSquareBrackets; - - /// Styles for adding spacing around ``:`` in bitfield definitions. - enum BitFieldColonSpacingStyle : unsigned char { - /// Add one space on each side of the ``:`` + struct SpacesInParensCustom { + /// Put a space in parentheses only inside conditional statements + /// (``for/if/while/switch...``). /// \code - /// unsigned bf : 2; + /// true: false: + /// if ( a ) { ... } vs. if (a) { ... } + /// while ( i < 5 ) { ... } while (i < 5) { ... } /// \endcode - BFCS_Both, - /// Add no space around the ``:`` (except when needed for - /// ``AlignConsecutiveBitFields``). + bool InConditionalStatements; + /// Put a space in C style casts. /// \code - /// unsigned bf:2; + /// true: false: + /// x = ( int32 )y vs. x = (int32)y /// \endcode - BFCS_None, - /// Add space before the ``:`` only + bool InCStyleCasts; + /// Put a space in parentheses only if the parentheses are empty i.e. '()' /// \code - /// unsigned bf :2; + /// true: false: + /// void f( ) { vs. void f() { + /// int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()}; + /// if (true) { if (true) { + /// f( ); f(); + /// } } + /// } } /// \endcode - BFCS_Before, - /// Add space after the ``:`` only (space may be added before if - /// needed for ``AlignConsecutiveBitFields``). + bool InEmptyParentheses; + /// Put a space in parentheses not covered by preceding options. /// \code - /// unsigned bf: 2; + /// true: false: + /// t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete; /// \endcode - BFCS_After + bool Other; + + SpacesInParensCustom() + : InConditionalStatements(false), InCStyleCasts(false), + InEmptyParentheses(false), Other(false) {} + + SpacesInParensCustom(bool InConditionalStatements, bool InCStyleCasts, + bool InEmptyParentheses, bool Other) + : InConditionalStatements(InConditionalStatements), + InCStyleCasts(InCStyleCasts), InEmptyParentheses(InEmptyParentheses), + Other(Other) {} + + bool operator==(const SpacesInParensCustom &R) const { + return InConditionalStatements == R.InConditionalStatements && + InCStyleCasts == R.InCStyleCasts && + InEmptyParentheses == R.InEmptyParentheses && Other == R.Other; + } + bool operator!=(const SpacesInParensCustom &R) const { + return !(*this == R); + } }; - /// The BitFieldColonSpacingStyle to use for bitfields. - BitFieldColonSpacingStyle BitFieldColonSpacing; + + /// Control of individual spaces in parentheses. + /// + /// If ``SpacesInParens`` is set to ``Custom``, use this to specify + /// how each individual space in parentheses case should be handled. + /// Otherwise, this is ignored. + /// \code{.yaml} + /// # Example of usage: + /// SpacesInParens: Custom + /// SpacesInParensOptions: + /// InConditionalStatements: true + /// InEmptyParentheses: true + /// \endcode + /// \version 17 + SpacesInParensCustom SpacesInParensOptions; + + /// If ``true``, spaces will be inserted after ``[`` and before ``]``. + /// Lambdas without arguments or unspecified size array declarations will not + /// be affected. + /// \code + /// true: false: + /// int a[ 5 ]; vs. int a[5]; + /// std::unique_ptr<int[]> foo() {} // Won't be affected + /// \endcode + /// \version 3.7 + bool SpacesInSquareBrackets; /// Supported language standards for parsing and formatting C++ constructs. /// \code @@ -2956,7 +4609,7 @@ struct FormatStyle { /// /// The correct way to spell a specific language version is e.g. ``c++11``. /// The historical aliases ``Cpp03`` and ``Cpp11`` are deprecated. - enum LanguageStandard : unsigned char { + enum LanguageStandard : int8_t { /// Parse and format as C++03. /// ``Cpp03`` is a deprecated alias for ``c++03`` LS_Cpp03, // c++03 @@ -2980,6 +4633,7 @@ struct FormatStyle { /// c++03: latest: /// vector<set<int> > x; vs. vector<set<int>> x; /// \endcode + /// \version 3.7 LanguageStandard Standard; /// Macros which are ignored in front of a statement, as if they were an @@ -2996,13 +4650,57 @@ struct FormatStyle { /// unsigned char data = 'x'; /// emit signal(data); // Now it's fine again. /// \endcode + /// \version 12 std::vector<std::string> StatementAttributeLikeMacros; + /// A vector of macros that should be interpreted as complete + /// statements. + /// + /// Typical macros are expressions, and require a semi-colon to be + /// added; sometimes this is not the case, and this allows to make + /// clang-format aware of such cases. + /// + /// For example: Q_UNUSED + /// \version 8 + std::vector<std::string> StatementMacros; + /// The number of columns used for tab stops. + /// \version 3.7 unsigned TabWidth; + /// A vector of non-keyword identifiers that should be interpreted as type + /// names. + /// + /// A ``*``, ``&``, or ``&&`` between a type name and another non-keyword + /// identifier is annotated as a pointer or reference token instead of a + /// binary operator. + /// + /// \version 17 + std::vector<std::string> TypeNames; + + /// \brief A vector of macros that should be interpreted as type declarations + /// instead of as function calls. + /// + /// These are expected to be macros of the form: + /// \code + /// STACK_OF(...) + /// \endcode + /// + /// In the .clang-format configuration file, this can be configured like: + /// \code{.yaml} + /// TypenameMacros: ['STACK_OF', 'LIST'] + /// \endcode + /// + /// For example: OpenSSL STACK_OF, BSD LIST_ENTRY. + /// \version 9 + std::vector<std::string> TypenameMacros; + + /// This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``. + /// \version 10 + // bool UseCRLF; + /// Different ways to use tab in formatting. - enum UseTabStyle : unsigned char { + enum UseTabStyle : int8_t { /// Never use tab. UT_Never, /// Use tabs only for indentation. @@ -3018,32 +4716,65 @@ struct FormatStyle { UT_Always }; - /// \brief Use ``\r\n`` instead of ``\n`` for line breaks. - /// Also used as fallback if ``DeriveLineEnding`` is true. - bool UseCRLF; - /// The way to use tab characters in the resulting file. + /// \version 3.7 UseTabStyle UseTab; + /// For Verilog, put each port on its own line in module instantiations. + /// \code + /// true: + /// ffnand ff1(.q(), + /// .qbar(out1), + /// .clear(in1), + /// .preset(in2)); + /// + /// false: + /// ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2)); + /// \endcode + /// \version 17 + bool VerilogBreakBetweenInstancePorts; + + /// A vector of macros which are whitespace-sensitive and should not + /// be touched. + /// + /// These are expected to be macros of the form: + /// \code + /// STRINGIZE(...) + /// \endcode + /// + /// In the .clang-format configuration file, this can be configured like: + /// \code{.yaml} + /// WhitespaceSensitiveMacros: ['STRINGIZE', 'PP_STRINGIZE'] + /// \endcode + /// + /// For example: BOOST_PP_STRINGIZE + /// \version 11 + std::vector<std::string> WhitespaceSensitiveMacros; + bool operator==(const FormatStyle &R) const { return AccessModifierOffset == R.AccessModifierOffset && AlignAfterOpenBracket == R.AlignAfterOpenBracket && + AlignArrayOfStructures == R.AlignArrayOfStructures && AlignConsecutiveAssignments == R.AlignConsecutiveAssignments && AlignConsecutiveBitFields == R.AlignConsecutiveBitFields && AlignConsecutiveDeclarations == R.AlignConsecutiveDeclarations && AlignConsecutiveMacros == R.AlignConsecutiveMacros && + AlignConsecutiveShortCaseStatements == + R.AlignConsecutiveShortCaseStatements && AlignEscapedNewlines == R.AlignEscapedNewlines && AlignOperands == R.AlignOperands && AlignTrailingComments == R.AlignTrailingComments && AllowAllArgumentsOnNextLine == R.AllowAllArgumentsOnNextLine && - AllowAllConstructorInitializersOnNextLine == - R.AllowAllConstructorInitializersOnNextLine && AllowAllParametersOfDeclarationOnNextLine == R.AllowAllParametersOfDeclarationOnNextLine && - AllowShortEnumsOnASingleLine == R.AllowShortEnumsOnASingleLine && + AllowBreakBeforeNoexceptSpecifier == + R.AllowBreakBeforeNoexceptSpecifier && AllowShortBlocksOnASingleLine == R.AllowShortBlocksOnASingleLine && AllowShortCaseLabelsOnASingleLine == R.AllowShortCaseLabelsOnASingleLine && + AllowShortCompoundRequirementOnASingleLine == + R.AllowShortCompoundRequirementOnASingleLine && + AllowShortEnumsOnASingleLine == R.AllowShortEnumsOnASingleLine && AllowShortFunctionsOnASingleLine == R.AllowShortFunctionsOnASingleLine && AllowShortIfStatementsOnASingleLine == @@ -3058,25 +4789,29 @@ struct FormatStyle { AttributeMacros == R.AttributeMacros && BinPackArguments == R.BinPackArguments && BinPackParameters == R.BinPackParameters && + BitFieldColonSpacing == R.BitFieldColonSpacing && + BracedInitializerIndentWidth == R.BracedInitializerIndentWidth && + BreakAdjacentStringLiterals == R.BreakAdjacentStringLiterals && + BreakAfterAttributes == R.BreakAfterAttributes && + BreakAfterJavaFieldAnnotations == R.BreakAfterJavaFieldAnnotations && + BreakArrays == R.BreakArrays && BreakBeforeBinaryOperators == R.BreakBeforeBinaryOperators && BreakBeforeBraces == R.BreakBeforeBraces && BreakBeforeConceptDeclarations == R.BreakBeforeConceptDeclarations && + BreakBeforeInlineASMColon == R.BreakBeforeInlineASMColon && BreakBeforeTernaryOperators == R.BreakBeforeTernaryOperators && BreakConstructorInitializers == R.BreakConstructorInitializers && - CompactNamespaces == R.CompactNamespaces && - BreakAfterJavaFieldAnnotations == R.BreakAfterJavaFieldAnnotations && + BreakInheritanceList == R.BreakInheritanceList && BreakStringLiterals == R.BreakStringLiterals && ColumnLimit == R.ColumnLimit && CommentPragmas == R.CommentPragmas && - BreakInheritanceList == R.BreakInheritanceList && - ConstructorInitializerAllOnOneLineOrOnePerLine == - R.ConstructorInitializerAllOnOneLineOrOnePerLine && + CompactNamespaces == R.CompactNamespaces && ConstructorInitializerIndentWidth == R.ConstructorInitializerIndentWidth && ContinuationIndentWidth == R.ContinuationIndentWidth && Cpp11BracedListStyle == R.Cpp11BracedListStyle && - DeriveLineEnding == R.DeriveLineEnding && DerivePointerAlignment == R.DerivePointerAlignment && DisableFormat == R.DisableFormat && + EmptyLineAfterAccessModifier == R.EmptyLineAfterAccessModifier && EmptyLineBeforeAccessModifier == R.EmptyLineBeforeAccessModifier && ExperimentalAutoDetectBinPacking == R.ExperimentalAutoDetectBinPacking && @@ -3088,21 +4823,28 @@ struct FormatStyle { R.IncludeStyle.IncludeIsMainRegex && IncludeStyle.IncludeIsMainSourceRegex == R.IncludeStyle.IncludeIsMainSourceRegex && - IndentCaseLabels == R.IndentCaseLabels && + IndentAccessModifiers == R.IndentAccessModifiers && IndentCaseBlocks == R.IndentCaseBlocks && + IndentCaseLabels == R.IndentCaseLabels && + IndentExternBlock == R.IndentExternBlock && IndentGotoLabels == R.IndentGotoLabels && IndentPPDirectives == R.IndentPPDirectives && - IndentExternBlock == R.IndentExternBlock && - IndentRequires == R.IndentRequires && IndentWidth == R.IndentWidth && - Language == R.Language && + IndentRequiresClause == R.IndentRequiresClause && + IndentWidth == R.IndentWidth && IndentWrappedFunctionNames == R.IndentWrappedFunctionNames && + InsertBraces == R.InsertBraces && + InsertNewlineAtEOF == R.InsertNewlineAtEOF && + IntegerLiteralSeparator == R.IntegerLiteralSeparator && JavaImportGroups == R.JavaImportGroups && JavaScriptQuotes == R.JavaScriptQuotes && JavaScriptWrapImports == R.JavaScriptWrapImports && + KeepEmptyLinesAtEOF == R.KeepEmptyLinesAtEOF && KeepEmptyLinesAtTheStartOfBlocks == R.KeepEmptyLinesAtTheStartOfBlocks && - MacroBlockBegin == R.MacroBlockBegin && - MacroBlockEnd == R.MacroBlockEnd && + Language == R.Language && + LambdaBodyIndentation == R.LambdaBodyIndentation && + LineEnding == R.LineEnding && MacroBlockBegin == R.MacroBlockBegin && + MacroBlockEnd == R.MacroBlockEnd && Macros == R.Macros && MaxEmptyLinesToKeep == R.MaxEmptyLinesToKeep && NamespaceIndentation == R.NamespaceIndentation && NamespaceMacros == R.NamespaceMacros && @@ -3110,20 +4852,36 @@ struct FormatStyle { ObjCBlockIndentWidth == R.ObjCBlockIndentWidth && ObjCBreakBeforeNestedBlockParam == R.ObjCBreakBeforeNestedBlockParam && + ObjCPropertyAttributeOrder == R.ObjCPropertyAttributeOrder && ObjCSpaceAfterProperty == R.ObjCSpaceAfterProperty && ObjCSpaceBeforeProtocolList == R.ObjCSpaceBeforeProtocolList && + PackConstructorInitializers == R.PackConstructorInitializers && PenaltyBreakAssignment == R.PenaltyBreakAssignment && PenaltyBreakBeforeFirstCallParameter == R.PenaltyBreakBeforeFirstCallParameter && PenaltyBreakComment == R.PenaltyBreakComment && PenaltyBreakFirstLessLess == R.PenaltyBreakFirstLessLess && + PenaltyBreakOpenParenthesis == R.PenaltyBreakOpenParenthesis && + PenaltyBreakScopeResolution == R.PenaltyBreakScopeResolution && PenaltyBreakString == R.PenaltyBreakString && - PenaltyExcessCharacter == R.PenaltyExcessCharacter && - PenaltyReturnTypeOnItsOwnLine == R.PenaltyReturnTypeOnItsOwnLine && PenaltyBreakTemplateDeclaration == R.PenaltyBreakTemplateDeclaration && + PenaltyExcessCharacter == R.PenaltyExcessCharacter && + PenaltyReturnTypeOnItsOwnLine == R.PenaltyReturnTypeOnItsOwnLine && PointerAlignment == R.PointerAlignment && + QualifierAlignment == R.QualifierAlignment && + QualifierOrder == R.QualifierOrder && RawStringFormats == R.RawStringFormats && + ReferenceAlignment == R.ReferenceAlignment && + RemoveBracesLLVM == R.RemoveBracesLLVM && + RemoveParentheses == R.RemoveParentheses && + RemoveSemicolon == R.RemoveSemicolon && + RequiresClausePosition == R.RequiresClausePosition && + RequiresExpressionIndentation == R.RequiresExpressionIndentation && + SeparateDefinitionBlocks == R.SeparateDefinitionBlocks && + ShortNamespaceLines == R.ShortNamespaceLines && + SkipMacroDefinitionBody == R.SkipMacroDefinitionBody && + SortIncludes == R.SortIncludes && SortJavaStaticImport == R.SortJavaStaticImport && SpaceAfterCStyleCast == R.SpaceAfterCStyleCast && SpaceAfterLogicalNot == R.SpaceAfterLogicalNot && @@ -3134,29 +4892,35 @@ struct FormatStyle { SpaceBeforeCtorInitializerColon == R.SpaceBeforeCtorInitializerColon && SpaceBeforeInheritanceColon == R.SpaceBeforeInheritanceColon && + SpaceBeforeJsonColon == R.SpaceBeforeJsonColon && SpaceBeforeParens == R.SpaceBeforeParens && + SpaceBeforeParensOptions == R.SpaceBeforeParensOptions && SpaceAroundPointerQualifiers == R.SpaceAroundPointerQualifiers && SpaceBeforeRangeBasedForLoopColon == R.SpaceBeforeRangeBasedForLoopColon && + SpaceBeforeSquareBrackets == R.SpaceBeforeSquareBrackets && SpaceInEmptyBlock == R.SpaceInEmptyBlock && - SpaceInEmptyParentheses == R.SpaceInEmptyParentheses && SpacesBeforeTrailingComments == R.SpacesBeforeTrailingComments && SpacesInAngles == R.SpacesInAngles && - SpacesInConditionalStatement == R.SpacesInConditionalStatement && SpacesInContainerLiterals == R.SpacesInContainerLiterals && - SpacesInCStyleCastParentheses == R.SpacesInCStyleCastParentheses && - SpacesInParentheses == R.SpacesInParentheses && + SpacesInLineCommentPrefix.Minimum == + R.SpacesInLineCommentPrefix.Minimum && + SpacesInLineCommentPrefix.Maximum == + R.SpacesInLineCommentPrefix.Maximum && + SpacesInParens == R.SpacesInParens && + SpacesInParensOptions == R.SpacesInParensOptions && SpacesInSquareBrackets == R.SpacesInSquareBrackets && - SpaceBeforeSquareBrackets == R.SpaceBeforeSquareBrackets && - BitFieldColonSpacing == R.BitFieldColonSpacing && Standard == R.Standard && StatementAttributeLikeMacros == R.StatementAttributeLikeMacros && StatementMacros == R.StatementMacros && TabWidth == R.TabWidth && - UseTab == R.UseTab && UseCRLF == R.UseCRLF && - TypenameMacros == R.TypenameMacros; + TypeNames == R.TypeNames && TypenameMacros == R.TypenameMacros && + UseTab == R.UseTab && + VerilogBreakBetweenInstancePorts == + R.VerilogBreakBetweenInstancePorts && + WhitespaceSensitiveMacros == R.WhitespaceSensitiveMacros; } - llvm::Optional<FormatStyle> GetLanguageStyle(LanguageKind Language) const; + std::optional<FormatStyle> GetLanguageStyle(LanguageKind Language) const; // Stores per-language styles. A FormatStyle instance inside has an empty // StyleSet. A FormatStyle instance returned by the Get method has its @@ -3168,7 +4932,7 @@ struct FormatStyle { struct FormatStyleSet { typedef std::map<FormatStyle::LanguageKind, FormatStyle> MapType; - llvm::Optional<FormatStyle> Get(FormatStyle::LanguageKind Language) const; + std::optional<FormatStyle> Get(FormatStyle::LanguageKind Language) const; // Adds \p Style to this FormatStyleSet. Style must not have an associated // FormatStyleSet. @@ -3191,9 +4955,11 @@ struct FormatStyle { private: FormatStyleSet StyleSet; - friend std::error_code parseConfiguration(llvm::MemoryBufferRef Config, - FormatStyle *Style, - bool AllowUnknownOptions); + friend std::error_code + parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style, + bool AllowUnknownOptions, + llvm::SourceMgr::DiagHandlerTy DiagHandler, + void *DiagHandlerCtxt); }; /// Returns a format style complying with the LLVM coding standards: @@ -3212,7 +4978,7 @@ FormatStyle getGoogleStyle(FormatStyle::LanguageKind Language); FormatStyle getChromiumStyle(FormatStyle::LanguageKind Language); /// Returns a format style complying with Mozilla's style guide: -/// https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style. +/// https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html. FormatStyle getMozillaStyle(); /// Returns a format style complying with Webkit's style guide: @@ -3227,6 +4993,8 @@ FormatStyle getGNUStyle(); /// https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017 FormatStyle getMicrosoftStyle(FormatStyle::LanguageKind Language); +FormatStyle getClangFormatStyle(); + /// Returns style indicating formatting should be not applied at all. FormatStyle getNoStyle(); @@ -3250,10 +5018,14 @@ bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language, /// document, are retained in \p Style. /// /// If AllowUnknownOptions is true, no errors are emitted if unknown -/// format options are occured. -std::error_code parseConfiguration(llvm::MemoryBufferRef Config, - FormatStyle *Style, - bool AllowUnknownOptions = false); +/// format options are occurred. +/// +/// If set all diagnostics are emitted through the DiagHandler. +std::error_code +parseConfiguration(llvm::MemoryBufferRef Config, FormatStyle *Style, + bool AllowUnknownOptions = false, + llvm::SourceMgr::DiagHandlerTy DiagHandler = nullptr, + void *DiagHandlerCtx = nullptr); /// Like above but accepts an unnamed buffer. inline std::error_code parseConfiguration(StringRef Config, FormatStyle *Style, @@ -3289,7 +5061,7 @@ formatReplacements(StringRef Code, const tooling::Replacements &Replaces, /// - If a replacement has offset UINT_MAX, length 1, and a replacement text /// that is the name of the header to be removed, the header will be removed /// from \p Code if it exists. -/// The include manipulation is done via `tooling::HeaderInclude`, see its +/// The include manipulation is done via ``tooling::HeaderInclude``, see its /// documentation for more details on how include insertion points are found and /// what edits are produced. llvm::Expected<tooling::Replacements> @@ -3348,6 +5120,17 @@ tooling::Replacements fixNamespaceEndComments(const FormatStyle &Style, ArrayRef<tooling::Range> Ranges, StringRef FileName = "<stdin>"); +/// Inserts or removes empty lines separating definition blocks including +/// classes, structs, functions, namespaces, and enums in the given \p Ranges in +/// \p Code. +/// +/// Returns the ``Replacements`` that inserts or removes empty lines separating +/// definition blocks in all \p Ranges in \p Code. +tooling::Replacements separateDefinitionBlocks(const FormatStyle &Style, + StringRef Code, + ArrayRef<tooling::Range> Ranges, + StringRef FileName = "<stdin>"); + /// Sort consecutive using declarations in the given \p Ranges in /// \p Code. /// @@ -3369,11 +5152,11 @@ LangOptions getFormattingLangOpts(const FormatStyle &Style = getLLVMStyle()); extern const char *StyleOptionHelpDescription; /// The suggested format style to use by default. This allows tools using -/// `getStyle` to have a consistent default style. +/// ``getStyle`` to have a consistent default style. /// Different builds can modify the value to the preferred styles. extern const char *DefaultFormatStyle; -/// The suggested predefined style to use as the fallback style in `getStyle`. +/// The suggested predefined style to use as the fallback style in ``getStyle``. /// Different builds can modify the value to the preferred styles. extern const char *DefaultFallbackStyle; @@ -3386,6 +5169,8 @@ extern const char *DefaultFallbackStyle; /// * "file" - Load style configuration from a file called ``.clang-format`` /// located in one of the parent directories of ``FileName`` or the current /// directory if ``FileName`` is empty. +/// * "file:<format_file_path>" to explicitly specify the configuration file to +/// use. /// /// \param[in] StyleName Style name to interpret according to the description /// above. @@ -3427,17 +5212,24 @@ inline StringRef getLanguageName(FormatStyle::LanguageKind Language) { return "Java"; case FormatStyle::LK_JavaScript: return "JavaScript"; + case FormatStyle::LK_Json: + return "Json"; case FormatStyle::LK_Proto: return "Proto"; case FormatStyle::LK_TableGen: return "TableGen"; case FormatStyle::LK_TextProto: return "TextProto"; + case FormatStyle::LK_Verilog: + return "Verilog"; default: return "Unknown"; } } +bool isClangFormatOn(StringRef Comment); +bool isClangFormatOff(StringRef Comment); + } // end namespace format } // end namespace clang |