Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 352742a

Browse files
author
Eugene Shalygin
committedApr 2, 2025·
[clang-format] option to control bin-packing keyworded parameters
The Q_PROPERTY declaration is almost like a function declaration, but uses keywords as parameter separators. This allows users to provide list of those keywords to be used to control bin-packing of the macro parameters.
1 parent 41d718b commit 352742a

13 files changed

+240
-3
lines changed
 

Diff for: ‎clang/docs/ClangFormatStyleOptions.rst

+32
Original file line numberDiff line numberDiff line change
@@ -4781,6 +4781,38 @@ the configuration (without a prefix: ``Auto``).
47814781
replaced with a single newline and form feed followed by the remaining
47824782
newlines.
47834783

4784+
.. _KeywordedFunctionLikeMacros:
4785+
4786+
**KeywordedFunctionLikeMacros** (``List of KeywordedFunctionLikeMacros``) :versionbadge:`clang-format 21` :ref:`<KeywordedFunctionLikeMacros>`
4787+
Allows to format function-like macros with keyworded parameters according
4788+
to the BinPackParameters setting, treating keywords as parameter
4789+
separators.
4790+
4791+
Q_PROPERTY is an example of such a macro:
4792+
4793+
.. code-block:: c++
4794+
4795+
Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)
4796+
4797+
With ``BinPackParameters`` set to ``OnePerLine`` (or
4798+
``AlwaysOnePerLine``) and
4799+
4800+
.. code-block:: yaml
4801+
4802+
KeywordedFunctionLikeMacros:
4803+
- Name: "Q_PROPERTY"
4804+
Keywords: ['READ', 'WRITE', 'MEMBER', 'RESET', 'NOTIFY']
4805+
4806+
the line above will be split on these keywords:
4807+
4808+
.. code-block:: c++
4809+
4810+
Q_PROPERTY(
4811+
int name
4812+
READ name
4813+
WRITE setName
4814+
NOTIFY nameChanged)
4815+
47844816
.. _LambdaBodyIndentation:
47854817

47864818
**LambdaBodyIndentation** (``LambdaBodyIndentationKind``) :versionbadge:`clang-format 13` :ref:`<LambdaBodyIndentation>`

Diff for: ‎clang/docs/ReleaseNotes.rst

+2
Original file line numberDiff line numberDiff line change
@@ -515,6 +515,8 @@ clang-format
515515
top of the file.
516516
- Add ``EnumTrailingComma`` option for inserting/removing commas at the end of
517517
``enum`` enumerator lists.
518+
- Allow to apply parameters bin-packing options to function-like macros that
519+
use keywords to delimit parameters (e.g. Q_PROPERTY).
518520

519521
libclang
520522
--------

Diff for: ‎clang/docs/tools/dump_format_style.py

+1
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,7 @@ class State:
462462
"std::string",
463463
"std::vector<std::string>",
464464
"std::vector<IncludeCategory>",
465+
"std::vector<KeywordedFunctionLikeMacro>",
465466
"std::vector<RawStringFormat>",
466467
"std::optional<unsigned>",
467468
"deprecated",

Diff for: ‎clang/docs/tools/plurals.txt

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
Strings
22
IncludeCategories
3+
KeywordedFunctionLikeMacros
34
RawStringFormats

Diff for: ‎clang/include/clang/Format/Format.h

+40
Original file line numberDiff line numberDiff line change
@@ -3309,6 +3309,45 @@ struct FormatStyle {
33093309
/// \version 20
33103310
bool KeepFormFeed;
33113311

3312+
/// Function-like declaration with keyworded parameters.
3313+
/// Lists possible keywords for a named function-like macro.
3314+
struct KeywordedFunctionLikeMacro {
3315+
std::string Name;
3316+
std::vector<std::string> Keywords;
3317+
3318+
bool operator==(const KeywordedFunctionLikeMacro &Other) const {
3319+
return Name == Other.Name && Keywords == Other.Keywords;
3320+
}
3321+
};
3322+
3323+
/// Allows to format function-like macros with keyworded parameters according
3324+
/// to the BinPackParameters setting, treating keywords as parameter
3325+
/// separators.
3326+
///
3327+
/// Q_PROPERTY is an example of such a macro:
3328+
/// \code
3329+
/// Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)
3330+
/// \endcode
3331+
///
3332+
/// With ``BinPackParameters`` set to ``OnePerLine`` (or
3333+
/// ``AlwaysOnePerLine``) and
3334+
/// \code{.yaml}
3335+
/// KeywordedFunctionLikeMacros:
3336+
/// - Name: "Q_PROPERTY"
3337+
/// Keywords: ['READ', 'WRITE', 'MEMBER', 'RESET', 'NOTIFY']
3338+
/// \endcode
3339+
///
3340+
/// the line above will be split on these keywords:
3341+
/// \code
3342+
/// Q_PROPERTY(
3343+
/// int name
3344+
/// READ name
3345+
/// WRITE setName
3346+
/// NOTIFY nameChanged)
3347+
/// \endcode
3348+
/// \version 21
3349+
std::vector<KeywordedFunctionLikeMacro> KeywordedFunctionLikeMacros;
3350+
33123351
/// Indentation logic for lambda bodies.
33133352
enum LambdaBodyIndentationKind : int8_t {
33143353
/// Align lambda body relative to the lambda signature. This is the default.
@@ -5386,6 +5425,7 @@ struct FormatStyle {
53865425
JavaScriptWrapImports == R.JavaScriptWrapImports &&
53875426
KeepEmptyLines == R.KeepEmptyLines &&
53885427
KeepFormFeed == R.KeepFormFeed && Language == R.Language &&
5428+
KeywordedFunctionLikeMacros == R.KeywordedFunctionLikeMacros &&
53895429
LambdaBodyIndentation == R.LambdaBodyIndentation &&
53905430
LineEnding == R.LineEnding && MacroBlockBegin == R.MacroBlockBegin &&
53915431
MacroBlockEnd == R.MacroBlockEnd && Macros == R.Macros &&

Diff for: ‎clang/lib/Format/ContinuationIndenter.cpp

+4
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,10 @@ bool ContinuationIndenter::canBreak(const LineState &State) {
349349
}
350350
}
351351

352+
// Don't break between function parameter keywords and parameter names.
353+
if (Previous.is(TT_FunctionParameterKeyword) && Current.is(TT_StartOfName))
354+
return false;
355+
352356
// Don't allow breaking before a closing brace of a block-indented braced list
353357
// initializer if there isn't already a break.
354358
if (Current.is(tok::r_brace) && Current.MatchingParen &&

Diff for: ‎clang/lib/Format/Format.cpp

+11
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828

2929
using clang::format::FormatStyle;
3030

31+
LLVM_YAML_IS_SEQUENCE_VECTOR(FormatStyle::KeywordedFunctionLikeMacro)
3132
LLVM_YAML_IS_SEQUENCE_VECTOR(FormatStyle::RawStringFormat)
3233

3334
namespace llvm {
@@ -408,6 +409,14 @@ template <> struct MappingTraits<FormatStyle::KeepEmptyLinesStyle> {
408409
}
409410
};
410411

412+
template <> struct MappingTraits<FormatStyle::KeywordedFunctionLikeMacro> {
413+
static void mapping(IO &IO,
414+
FormatStyle::KeywordedFunctionLikeMacro &Function) {
415+
IO.mapOptional("Name", Function.Name);
416+
IO.mapOptional("Keywords", Function.Keywords);
417+
}
418+
};
419+
411420
template <> struct ScalarEnumerationTraits<FormatStyle::LanguageKind> {
412421
static void enumeration(IO &IO, FormatStyle::LanguageKind &Value) {
413422
IO.enumCase(Value, "C", FormatStyle::LK_C);
@@ -1082,6 +1091,8 @@ template <> struct MappingTraits<FormatStyle> {
10821091
IO.mapOptional("JavaScriptWrapImports", Style.JavaScriptWrapImports);
10831092
IO.mapOptional("KeepEmptyLines", Style.KeepEmptyLines);
10841093
IO.mapOptional("KeepFormFeed", Style.KeepFormFeed);
1094+
IO.mapOptional("KeywordedFunctionLikeMacros",
1095+
Style.KeywordedFunctionLikeMacros);
10851096
IO.mapOptional("LambdaBodyIndentation", Style.LambdaBodyIndentation);
10861097
IO.mapOptional("LineEnding", Style.LineEnding);
10871098
IO.mapOptional("MacroBlockBegin", Style.MacroBlockBegin);

Diff for: ‎clang/lib/Format/FormatToken.cpp

+2
Original file line numberDiff line numberDiff line change
@@ -331,6 +331,8 @@ bool startsNextParameter(const FormatToken &Current, const FormatStyle &Style) {
331331
}
332332
if (Style.Language == FormatStyle::LK_Proto && Current.is(TT_SelectorName))
333333
return true;
334+
if (Current.is(TT_FunctionParameterKeyword))
335+
return true;
334336
return Previous.is(tok::comma) && !Current.isTrailingComment() &&
335337
((Previous.isNot(TT_CtorInitializerComma) ||
336338
Style.BreakConstructorInitializers !=

Diff for: ‎clang/lib/Format/FormatToken.h

+1
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ namespace format {
8484
TYPE(FunctionDeclarationLParen) \
8585
TYPE(FunctionLBrace) \
8686
TYPE(FunctionLikeOrFreestandingMacro) \
87+
TYPE(FunctionParameterKeyword) \
8788
TYPE(FunctionTypeLParen) \
8889
/* The colons as part of a C11 _Generic selection */ \
8990
TYPE(GenericSelectionColon) \

Diff for: ‎clang/lib/Format/TokenAnnotator.cpp

+44-3
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,16 @@ static bool isCppAttribute(bool IsCpp, const FormatToken &Tok) {
116116
return AttrTok && AttrTok->startsSequence(tok::r_square, tok::r_square);
117117
}
118118

119+
static bool isParametersKeyword(
120+
const FormatToken &Tok,
121+
const FormatStyle::KeywordedFunctionLikeMacro *declaration) {
122+
if (!declaration)
123+
return false;
124+
125+
return std::find(declaration->Keywords.begin(), declaration->Keywords.end(),
126+
Tok.TokenText) != declaration->Keywords.end();
127+
}
128+
119129
/// A parser that gathers additional information about tokens.
120130
///
121131
/// The \c TokenAnnotator tries to match parenthesis and square brakets and
@@ -148,6 +158,32 @@ class AnnotatingParser {
148158
}
149159
}
150160

161+
const FormatStyle::KeywordedFunctionLikeMacro *
162+
findKeywordedFunctionLikeMacro() const {
163+
const FormatToken *TokBeforeFirstLParent = nullptr;
164+
for (const FormatToken *T = Line.First; T != Line.Last; T = T->Next) {
165+
if (T->Tok.is(tok::l_paren)) {
166+
TokBeforeFirstLParent = T->getPreviousNonComment();
167+
break;
168+
}
169+
}
170+
171+
// Unknown if line ends with ';', FunctionLikeOrFreestandingMacro otherwise.
172+
if (!TokBeforeFirstLParent ||
173+
!TokBeforeFirstLParent->isOneOf(TT_FunctionLikeOrFreestandingMacro,
174+
TT_Unknown)) {
175+
return nullptr;
176+
}
177+
auto I = std::find_if(
178+
Style.KeywordedFunctionLikeMacros.begin(),
179+
Style.KeywordedFunctionLikeMacros.end(),
180+
[TokBeforeFirstLParent](
181+
const FormatStyle::KeywordedFunctionLikeMacro &Declaration) {
182+
return TokBeforeFirstLParent->TokenText == Declaration.Name;
183+
});
184+
return I != Style.KeywordedFunctionLikeMacros.end() ? &*I : nullptr;
185+
}
186+
151187
bool parseAngle() {
152188
if (!CurrentToken)
153189
return false;
@@ -2419,8 +2455,12 @@ class AnnotatingParser {
24192455
Current.setType(TT_BinaryOperator);
24202456
} else if (isStartOfName(Current) &&
24212457
(!Line.MightBeFunctionDecl || Current.NestingLevel != 0)) {
2422-
Contexts.back().FirstStartOfName = &Current;
2423-
Current.setType(TT_StartOfName);
2458+
if (isParametersKeyword(Current, findKeywordedFunctionLikeMacro())) {
2459+
Current.setType(TT_FunctionParameterKeyword);
2460+
} else {
2461+
Contexts.back().FirstStartOfName = &Current;
2462+
Current.setType(TT_StartOfName);
2463+
}
24242464
} else if (Current.is(tok::semi)) {
24252465
// Reset FirstStartOfName after finding a semicolon so that a for loop
24262466
// with multiple increment statements is not confused with a for loop
@@ -6235,7 +6275,8 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line,
62356275
Right.Next->isOneOf(TT_FunctionDeclarationName, tok::kw_const)));
62366276
}
62376277
if (Right.isOneOf(TT_StartOfName, TT_FunctionDeclarationName,
6238-
TT_ClassHeadName, tok::kw_operator)) {
6278+
TT_FunctionParameterKeyword, TT_ClassHeadName,
6279+
tok::kw_operator)) {
62396280
return true;
62406281
}
62416282
if (Right.isAttribute())

Diff for: ‎clang/unittests/Format/ConfigParseTest.cpp

+10
Original file line numberDiff line numberDiff line change
@@ -1113,6 +1113,16 @@ TEST(ConfigParseTest, ParsesConfiguration) {
11131113
FormatStyle::SDS_Leave);
11141114
CHECK_PARSE("SeparateDefinitionBlocks: Never", SeparateDefinitionBlocks,
11151115
FormatStyle::SDS_Never);
1116+
1117+
Style.KeywordedFunctionLikeMacros.clear();
1118+
std::vector<FormatStyle::KeywordedFunctionLikeMacro> ExpectedFunctions = {
1119+
{"MACRO_A", {"PARAM1", "KEYWORD", "KW_2"}}, {"macro", {"mKW1", "mKW2"}}};
1120+
CHECK_PARSE("KeywordedFunctionLikeMacros:\n"
1121+
" - Name: MACRO_A\n"
1122+
" Keywords: ['PARAM1', 'KEYWORD', 'KW_2']\n"
1123+
" - Name: macro\n"
1124+
" Keywords: [ \"mKW1\", \"mKW2\" ]\n",
1125+
KeywordedFunctionLikeMacros, ExpectedFunctions);
11161126
}
11171127

11181128
TEST(ConfigParseTest, ParsesConfigurationWithLanguages) {

Diff for: ‎clang/unittests/Format/FormatTest.cpp

+59
Original file line numberDiff line numberDiff line change
@@ -29134,6 +29134,65 @@ TEST_F(FormatTest, BreakBeforeClassName) {
2913429134
" ArenaSafeUniquePtr {};");
2913529135
}
2913629136

29137+
TEST_F(FormatTest, KeywordedFunctionLikeMacros) {
29138+
FormatStyle::KeywordedFunctionLikeMacro QPropertyDeclaration;
29139+
QPropertyDeclaration.Name = "Q_PROPERTY";
29140+
QPropertyDeclaration.Keywords.push_back("READ");
29141+
QPropertyDeclaration.Keywords.push_back("WRITE");
29142+
QPropertyDeclaration.Keywords.push_back("NOTIFY");
29143+
QPropertyDeclaration.Keywords.push_back("RESET");
29144+
29145+
auto Style40 = getLLVMStyleWithColumns(40);
29146+
Style40.KeywordedFunctionLikeMacros.push_back(QPropertyDeclaration);
29147+
Style40.BinPackParameters = FormatStyle::BPPS_OnePerLine;
29148+
29149+
verifyFormat("Q_PROPERTY(int name\n"
29150+
" READ name\n"
29151+
" WRITE setName\n"
29152+
" NOTIFY nameChanged)",
29153+
Style40);
29154+
verifyFormat("class A {\n"
29155+
" Q_PROPERTY(int name\n"
29156+
" READ name\n"
29157+
" WRITE setName\n"
29158+
" NOTIFY nameChanged)\n"
29159+
"};",
29160+
Style40);
29161+
verifyFormat("/* sdf */ Q_PROPERTY(int name\n"
29162+
" READ name\n"
29163+
" WRITE setName\n"
29164+
" NOTIFY nameChanged)",
29165+
Style40);
29166+
29167+
auto Style120 = getLLVMStyleWithColumns(120);
29168+
Style120.KeywordedFunctionLikeMacros.push_back(QPropertyDeclaration);
29169+
Style120.BinPackParameters = FormatStyle::BPPS_AlwaysOnePerLine;
29170+
29171+
verifyFormat("Q_PROPERTY(int name\n"
29172+
" READ name\n"
29173+
" WRITE setName\n"
29174+
" NOTIFY nameChanged)",
29175+
Style120);
29176+
verifyFormat("class A {\n"
29177+
" Q_PROPERTY(int name\n"
29178+
" READ name\n"
29179+
" WRITE setName\n"
29180+
" NOTIFY nameChanged)\n"
29181+
"};",
29182+
Style120);
29183+
29184+
Style120.BinPackParameters = FormatStyle::BPPS_BinPack;
29185+
29186+
verifyFormat(
29187+
"Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)",
29188+
Style120);
29189+
29190+
Style120.BinPackParameters = FormatStyle::BPPS_OnePerLine;
29191+
verifyFormat(
29192+
"Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)",
29193+
Style120);
29194+
}
29195+
2913729196
} // namespace
2913829197
} // namespace test
2913929198
} // namespace format

Diff for: ‎clang/unittests/Format/TokenAnnotatorTest.cpp

+33
Original file line numberDiff line numberDiff line change
@@ -3930,6 +3930,39 @@ TEST_F(TokenAnnotatorTest, UserDefinedConversionFunction) {
39303930
EXPECT_TOKEN(Tokens[5], tok::l_paren, TT_FunctionDeclarationLParen);
39313931
}
39323932

3933+
TEST_F(TokenAnnotatorTest, KeywordedFunctionLikeMacro) {
3934+
auto Style = getLLVMStyle();
3935+
FormatStyle::KeywordedFunctionLikeMacro QPropertyDeclaration;
3936+
QPropertyDeclaration.Name = "Q_PROPERTY";
3937+
QPropertyDeclaration.Keywords.push_back("READ");
3938+
QPropertyDeclaration.Keywords.push_back("WRITE");
3939+
QPropertyDeclaration.Keywords.push_back("NOTIFY");
3940+
QPropertyDeclaration.Keywords.push_back("RESET");
3941+
Style.KeywordedFunctionLikeMacros.push_back(QPropertyDeclaration);
3942+
3943+
auto Tokens = annotate(
3944+
"Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)",
3945+
Style);
3946+
ASSERT_EQ(Tokens.size(), 12u) << Tokens;
3947+
EXPECT_TOKEN(Tokens[0], tok::identifier, TT_Unknown);
3948+
EXPECT_TOKEN(Tokens[4], tok::identifier, TT_FunctionParameterKeyword);
3949+
EXPECT_TOKEN(Tokens[5], tok::identifier, TT_StartOfName);
3950+
EXPECT_TOKEN(Tokens[6], tok::identifier, TT_FunctionParameterKeyword);
3951+
EXPECT_TOKEN(Tokens[7], tok::identifier, TT_StartOfName);
3952+
EXPECT_TOKEN(Tokens[8], tok::identifier, TT_FunctionParameterKeyword);
3953+
EXPECT_TOKEN(Tokens[9], tok::identifier, TT_StartOfName);
3954+
3955+
Tokens = annotate("struct S { Q_OBJECT\n"
3956+
"Q_PROPERTY(int value READ value WRITE setValue "
3957+
"NOTIFY valueChanged)\n };",
3958+
Style);
3959+
ASSERT_EQ(Tokens.size(), 18u) << Tokens;
3960+
EXPECT_TOKEN(Tokens[4], tok::identifier, TT_FunctionLikeOrFreestandingMacro);
3961+
EXPECT_TOKEN(Tokens[8], tok::identifier, TT_FunctionParameterKeyword);
3962+
EXPECT_TOKEN(Tokens[10], tok::identifier, TT_FunctionParameterKeyword);
3963+
EXPECT_TOKEN(Tokens[12], tok::identifier, TT_FunctionParameterKeyword);
3964+
}
3965+
39333966
} // namespace
39343967
} // namespace format
39353968
} // namespace clang

0 commit comments

Comments
 (0)
Please sign in to comment.