[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.

Author: Eugene Shalygin

clang/docs/ClangFormatStyleOptions.rst

@@ -4032,6 +4032,38 @@ the configuration (without a prefix: ``Auto``).
 
  For example: BOOST_FOREACH.
 
+.. _FunctionDeclarationsWithKeywords:
+
+**FunctionDeclarationsWithKeywords** (``List of FunctionDeclarationWithKeywordes``) :versionbadge:`clang-format 21` :ref:`¶ <FunctionDeclarationsWithKeywords>`
+ Allows to format function-like macros with keyworded parameters according
+ to the BinPackParameters setting, treating keywords as parameter
+ sepratators.
+
+ Q_PROPERTY is an example of such a macro:
+
+ .. code-block:: c++
+
+ Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)
+
+ With ``BinPackParameters`` set to ``OnePerLine`` (or
+ ``AlwaysOnePerLine``) and
+
+ .. code-block:: yaml
+
+ FunctionDeclarationsWithKeywords:
+ - Name: "Q_PROPERTY"
+ Keywords: ['READ', 'WRITE', 'MEMBER', 'RESET', 'NOTIFY']
+
+ the line above will be split on these keywords:
+
+ .. code-block:: c++
+
+ Q_PROPERTY(
+ int name
+ READ name
+ WRITE setName
+ NOTIFY nameChanged)
+
 .. _IfMacros:
 
 **IfMacros** (``List of Strings``) :versionbadge:`clang-format 13` :ref:`¶ <IfMacros>`

clang/docs/tools/dump_format_style.py

@@ -461,6 +461,7 @@ class State:
  "int",
  "std::string",
  "std::vector<std::string>",
+ "std::vector<FunctionDeclarationWithKeywords>",
  "std::vector<IncludeCategory>",
  "std::vector<RawStringFormat>",
  "std::optional<unsigned>",

clang/docs/tools/plurals.txt

@@ -1,3 +1,4 @@
 Strings
+FunctionDeclarationWithKeywordes
 IncludeCategories
 RawStringFormats

clang/include/clang/Format/Format.h

@@ -2753,6 +2753,45 @@ struct FormatStyle {
  /// \version 3.7
  std::vector<std::string> ForEachMacros;
 
+ /// Function-like declaration with keyworded parameters.
+ /// Lists possible keywords for a named macro-like function
+ struct FunctionDeclarationWithKeywords {
+ std::string Name;
+ std::vector<std::string> Keywords;
+
+ bool operator==(const FunctionDeclarationWithKeywords &Other) const {
+ return Name == Other.Name && Keywords == Other.Keywords;
+ }
+ };
+
+ /// Allows to format function-like macros with keyworded parameters according
+ /// to the BinPackParameters setting, treating keywords as parameter
+ /// sepratators.
+ ///
+ /// Q_PROPERTY is an example of such a macro:
+ /// \code
+ /// Q_PROPERTY(int name READ name WRITE setName NOTIFY nameChanged)
+ /// \endcode
+ ///
+ /// With ``BinPackParameters`` set to ``OnePerLine`` (or
+ /// ``AlwaysOnePerLine``) and
+ /// \code{.yaml}
+ /// FunctionDeclarationsWithKeywords:
+ /// - Name: "Q_PROPERTY"
+ /// Keywords: ['READ', 'WRITE', 'MEMBER', 'RESET', 'NOTIFY']
+ /// \endcode
+ ///
+ /// the line above will be split on these keywords:
+ /// \code
+ /// Q_PROPERTY(
+ /// int name
+ /// READ name
+ /// WRITE setName
+ /// NOTIFY nameChanged)
+ /// \endcode
+ /// \version 21
+ std::vector<FunctionDeclarationWithKeywords> FunctionDeclarationsWithKeywords;
+
  tooling::IncludeStyle IncludeStyle;
 
  /// A vector of macros that should be interpreted as conditionals
@@ -5327,6 +5366,8 @@ struct FormatStyle {
  R.ExperimentalAutoDetectBinPacking &&
  FixNamespaceComments == R.FixNamespaceComments &&
  ForEachMacros == R.ForEachMacros &&
+ FunctionDeclarationsWithKeywords ==
+ R.FunctionDeclarationsWithKeywords &&
  IncludeStyle.IncludeBlocks == R.IncludeStyle.IncludeBlocks &&
  IncludeStyle.IncludeCategories == R.IncludeStyle.IncludeCategories &&
  IncludeStyle.IncludeIsMainRegex ==

clang/lib/Format/ContinuationIndenter.cpp

@@ -349,6 +349,10 @@ bool ContinuationIndenter::canBreak(const LineState &State) {
  }
  }
 
+ // Don't break between function parameter keywords and parameter names.
+ if (Previous.is(TT_FunctionParameterKeyword) && Current.is(TT_StartOfName))
+ return false;
+
  // Don't allow breaking before a closing brace of a block-indented braced list
  // initializer if there isn't already a break.
  if (Current.is(tok::r_brace) && Current.MatchingParen &&

clang/lib/Format/Format.cpp

@@ -29,6 +29,7 @@
 using clang::format::FormatStyle;
 
 LLVM_YAML_IS_SEQUENCE_VECTOR(FormatStyle::RawStringFormat)
+LLVM_YAML_IS_SEQUENCE_VECTOR(FormatStyle::FunctionDeclarationWithKeywords)
 
 namespace llvm {
 namespace yaml {
@@ -852,6 +853,14 @@ struct ScalarEnumerationTraits<
  }
 };
 
+template <> struct MappingTraits<FormatStyle::FunctionDeclarationWithKeywords> {
+ static void mapping(IO &IO,
+ FormatStyle::FunctionDeclarationWithKeywords &Function) {
+ IO.mapOptional("Name", Function.Name);
+ IO.mapOptional("Keywords", Function.Keywords);
+ }
+};
+
 template <> struct MappingTraits<FormatStyle> {
  static void mapping(IO &IO, FormatStyle &Style) {
  // When reading, read the language first, we need it for getPredefinedStyle.
@@ -1046,6 +1055,8 @@ template <> struct MappingTraits<FormatStyle> {
  Style.ExperimentalAutoDetectBinPacking);
  IO.mapOptional("FixNamespaceComments", Style.FixNamespaceComments);
  IO.mapOptional("ForEachMacros", Style.ForEachMacros);
+ IO.mapOptional("FunctionDeclarationsWithKeywords",
+ Style.FunctionDeclarationsWithKeywords);
  IO.mapOptional("IfMacros", Style.IfMacros);
  IO.mapOptional("IncludeBlocks", Style.IncludeStyle.IncludeBlocks);
  IO.mapOptional("IncludeCategories", Style.IncludeStyle.IncludeCategories);

clang/lib/Format/FormatToken.cpp

@@ -331,6 +331,8 @@ bool startsNextParameter(const FormatToken &Current, const FormatStyle &Style) {
  }
  if (Style.Language == FormatStyle::LK_Proto && Current.is(TT_SelectorName))
  return true;
+ if (Current.is(TT_FunctionParameterKeyword))
+ return true;
  return Previous.is(tok::comma) && !Current.isTrailingComment() &&
  ((Previous.isNot(TT_CtorInitializerComma) ||
  Style.BreakConstructorInitializers !=

clang/lib/Format/FormatToken.h

@@ -84,6 +84,7 @@ namespace format {
  TYPE(FunctionDeclarationLParen) \
  TYPE(FunctionLBrace) \
  TYPE(FunctionLikeOrFreestandingMacro) \
+ TYPE(FunctionParameterKeyword) \
  TYPE(FunctionTypeLParen) \
  /* The colons as part of a C11 _Generic selection */ \
  TYPE(GenericSelectionColon) \

clang/lib/Format/TokenAnnotator.cpp

@@ -116,6 +116,16 @@ static bool isCppAttribute(bool IsCpp, const FormatToken &Tok) {
  return AttrTok && AttrTok->startsSequence(tok::r_square, tok::r_square);
 }
 
+static bool isParametersKeyword(
+ const FormatToken &Tok,
+ const FormatStyle::FunctionDeclarationWithKeywords *declaration) {
+ if (!declaration)
+ return false;
+
+ return std::find(declaration->Keywords.begin(), declaration->Keywords.end(),
+ Tok.TokenText) != declaration->Keywords.end();
+}
+
 /// A parser that gathers additional information about tokens.
 ///
 /// The \c TokenAnnotator tries to match parenthesis and square brakets and
@@ -148,6 +158,23 @@ class AnnotatingParser {
  }
  }
 
+ const FormatStyle::FunctionDeclarationWithKeywords *
+ findSurroundingFunctionWithKeywordedParameters() const {
+ // Unknown if line ends with ';', FunctionLikeOrFreestandingMacro otherwise.
+ if (!Line.First ||
+ !Line.First->isOneOf(TT_FunctionLikeOrFreestandingMacro, TT_Unknown)) {
+ return nullptr;
+ }
+ auto I = std::find_if(
+ Style.FunctionDeclarationsWithKeywords.begin(),
+ Style.FunctionDeclarationsWithKeywords.end(),
+ [this](
+ const FormatStyle::FunctionDeclarationWithKeywords &Declaration) {
+ return Line.First->TokenText == Declaration.Name;
+ });
+ return I != Style.FunctionDeclarationsWithKeywords.end() ? &*I : nullptr;
+ }
+
  bool parseAngle() {
  if (!CurrentToken)
  return false;
@@ -2416,8 +2443,13 @@ class AnnotatingParser {
  Current.setType(TT_BinaryOperator);
  } else if (isStartOfName(Current) &&
  (!Line.MightBeFunctionDecl || Current.NestingLevel != 0)) {
- Contexts.back().FirstStartOfName = &Current;
- Current.setType(TT_StartOfName);
+ if (isParametersKeyword(
+ Current, findSurroundingFunctionWithKeywordedParameters())) {
+ Current.setType(TT_FunctionParameterKeyword);
+ } else {
+ Contexts.back().FirstStartOfName = &Current;
+ Current.setType(TT_StartOfName);
+ }
  } else if (Current.is(tok::semi)) {
  // Reset FirstStartOfName after finding a semicolon so that a for loop
  // with multiple increment statements is not confused with a for loop
@@ -3784,10 +3816,20 @@ void TokenAnnotator::annotate(AnnotatedLine &Line) {
 static bool isFunctionDeclarationName(const LangOptions &LangOpts,
  const FormatToken &Current,
  const AnnotatedLine &Line,
+ const FormatStyle &Style,
  FormatToken *&ClosingParen) {
  if (Current.is(TT_FunctionDeclarationName))
  return true;
 
+ if (Current.is(TT_FunctionLikeOrFreestandingMacro) &&
+ std::find_if(
+ Style.FunctionDeclarationsWithKeywords.begin(),
+ Style.FunctionDeclarationsWithKeywords.end(),
+ [&Current](const FormatStyle::FunctionDeclarationWithKeywords &Decl) {
+ return Current.TokenText == Decl.Name;
+ }) != Style.FunctionDeclarationsWithKeywords.end()) {
+ return true;
+ }
  if (!Current.Tok.getIdentifierInfo())
  return false;
 
@@ -3994,7 +4036,7 @@ void TokenAnnotator::calculateFormattingInformation(AnnotatedLine &Line) const {
  AfterLastAttribute = Tok;
  if (const bool IsCtorOrDtor = Tok->is(TT_CtorDtorDeclName);
  IsCtorOrDtor ||
- isFunctionDeclarationName(LangOpts, *Tok, Line, ClosingParen)) {
+ isFunctionDeclarationName(LangOpts, *Tok, Line, Style, ClosingParen)) {
  if (!IsCtorOrDtor)
  Tok->setFinalizedType(TT_FunctionDeclarationName);
  LineIsFunctionDeclaration = true;
@@ -6218,7 +6260,8 @@ bool TokenAnnotator::canBreakBefore(const AnnotatedLine &Line,
  Right.Next->isOneOf(TT_FunctionDeclarationName, tok::kw_const)));
  }
  if (Right.isOneOf(TT_StartOfName, TT_FunctionDeclarationName,
- TT_ClassHeadName, tok::kw_operator)) {
+ TT_FunctionParameterKeyword, TT_ClassHeadName,
+ tok::kw_operator)) {
  return true;
  }
  if (Right.isAttribute())

clang/unittests/Format/ConfigParseTest.cpp

@@ -1105,6 +1105,16 @@ TEST(ConfigParseTest, ParsesConfiguration) {
  FormatStyle::SDS_Leave);
  CHECK_PARSE("SeparateDefinitionBlocks: Never", SeparateDefinitionBlocks,
  FormatStyle::SDS_Never);
+
+ Style.FunctionDeclarationsWithKeywords.clear();
+ std::vector<FormatStyle::FunctionDeclarationWithKeywords> ExpectedFunctions =
+ {{"MACRO_A", {"PARAM1", "KEYWORD", "KW_2"}}, {"macro", {"mKW1", "mKW2"}}};
+ CHECK_PARSE("FunctionDeclarationsWithKeywords:\n"
+ " - Name: MACRO_A\n"
+ " Keywords: ['PARAM1', 'KEYWORD', 'KW_2']\n"
+ " - Name: macro\n"
+ " Keywords: [ \"mKW1\", \"mKW2\" ]\n",
+ FunctionDeclarationsWithKeywords, ExpectedFunctions);
 }
 
 TEST(ConfigParseTest, ParsesConfigurationWithLanguages) {