Introduce multilineTrailingCommaBehavior configuration

Author: TTOzzi

Documentation/Configuration.md

@@ -194,6 +194,21 @@ switch someValue {
 
 ---
 
+### `multilineTrailingCommaBehavior`  
+**type:** `string`
+
+**description:** Determines how trailing commas in comma-separated lists should be handled during formatting.
+
+- If set to `"alwaysUsed"`, a trailing comma is always added in multi-line lists.  
+- If set to `"neverUsed"`, trailing commas are removed even in multi-line lists.  
+- If set to `"keptAsWritten"` (the default), existing commas are preserved as-is, and for collections, the behavior falls back to the `multiElementCollectionTrailingCommas`.  
+
+This option takes precedence over `multiElementCollectionTrailingCommas`, unless it is set to `"keptAsWritten"`.  
+
+**default:** `"keptAsWritten"`  
+
+---
+
 ### `multiElementCollectionTrailingCommas`  
 **type:** boolean  
 

Sources/SwiftFormat/API/Configuration+Default.swift

@@ -39,6 +39,7 @@ extension Configuration {
     self.indentSwitchCaseLabels = false
     self.spacesAroundRangeFormationOperators = false
     self.noAssignmentInExpressions = NoAssignmentInExpressionsConfiguration()
+    self.multilineTrailingCommaBehavior = .keptAsWritten
     self.multiElementCollectionTrailingCommas = true
     self.reflowMultilineStringLiterals = .never
     self.indentBlankLines = false

Sources/SwiftFormat/API/Configuration.swift

@@ -44,6 +44,7 @@ public struct Configuration: Codable, Equatable {
     case rules
     case spacesAroundRangeFormationOperators
     case noAssignmentInExpressions
+    case multilineTrailingCommaBehavior
     case multiElementCollectionTrailingCommas
     case reflowMultilineStringLiterals
     case indentBlankLines
@@ -173,6 +174,22 @@ public struct Configuration: Codable, Equatable {
   /// Contains exceptions for the `NoAssignmentInExpressions` rule.
   public var noAssignmentInExpressions: NoAssignmentInExpressionsConfiguration
 
+  /// Determines how trailing commas in comma-separated lists should be handled during formatting.
+  public enum MultilineTrailingCommaBehavior: String, Codable {
+    case alwaysUsed
+    case neverUsed
+    case keptAsWritten
+  }
+
+  /// Determines how trailing commas in multiline comma-separated lists are handled during formatting.
+  ///
+  /// This setting takes precedence over `multiElementCollectionTrailingCommas`.
+  /// If set to `.keptAsWritten` (the default), the formatter defers to `multiElementCollectionTrailingCommas`
+  /// for collections only. In all other cases, existing trailing commas are preserved as-is and not modified.
+  /// If set to `.alwaysUsed` or `.neverUsed`, that behavior is applied uniformly across all list types,
+  /// regardless of `multiElementCollectionTrailingCommas`.
+  public var multilineTrailingCommaBehavior: MultilineTrailingCommaBehavior
+
   /// Determines if multi-element collection literals should have trailing commas.
   ///
   /// When `true` (default), the correct form is:
@@ -384,6 +401,9 @@ public struct Configuration: Codable, Equatable {
         forKey: .noAssignmentInExpressions
       )
       ?? defaults.noAssignmentInExpressions
+    self.multilineTrailingCommaBehavior =
+      try container.decodeIfPresent(MultilineTrailingCommaBehavior.self, forKey: .multilineTrailingCommaBehavior)
+      ?? defaults.multilineTrailingCommaBehavior
     self.multiElementCollectionTrailingCommas =
       try container.decodeIfPresent(
         Bool.self,

Sources/SwiftFormat/Core/SyntaxTraits.swift

@@ -65,3 +65,70 @@ extension ExprSyntax {
     return self.asProtocol(KeywordModifiedExprSyntaxProtocol.self) != nil
   }
 }
+
+/// Common protocol implemented by comma-separated lists whose elements
+/// support a `trailingComma`.
+protocol CommaSeparatedListSyntaxProtocol: SyntaxCollection where Element: WithTrailingCommaSyntax & Equatable {
+  /// The node used for trailing comma handling; inserted immediately after this node.
+  var lastNodeForTrailingComma: SyntaxProtocol? { get }
+}
+
+extension ArrayElementListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? { last?.expression }
+}
+extension DictionaryElementListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? { last }
+}
+extension LabeledExprListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? { last?.expression }
+}
+extension ClosureCaptureListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? {
+    if let initializer = last?.initializer {
+      return initializer
+    } else {
+      return last?.name
+    }
+  }
+}
+extension EnumCaseParameterListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? {
+    if let defaultValue = last?.defaultValue {
+      return defaultValue
+    } else {
+      return last?.type
+    }
+  }
+}
+extension FunctionParameterListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? {
+    if let defaultValue = last?.defaultValue {
+      return defaultValue
+    } else if let ellipsis = last?.ellipsis {
+      return ellipsis
+    } else {
+      return last?.type
+    }
+  }
+}
+extension GenericParameterListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? {
+    if let inheritedType = last?.inheritedType {
+      return inheritedType
+    } else {
+      return last?.name
+    }
+  }
+}
+extension TuplePatternElementListSyntax: CommaSeparatedListSyntaxProtocol {
+  var lastNodeForTrailingComma: SyntaxProtocol? { last?.pattern }
+}
+
+extension SyntaxProtocol {
+  func asProtocol(_: (any CommaSeparatedListSyntaxProtocol).Protocol) -> (any CommaSeparatedListSyntaxProtocol)? {
+    return Syntax(self).asProtocol(SyntaxProtocol.self) as? (any CommaSeparatedListSyntaxProtocol)
+  }
+  func isProtocol(_: (any CommaSeparatedListSyntaxProtocol).Protocol) -> Bool {
+    return self.asProtocol((any CommaSeparatedListSyntaxProtocol).self) != nil
+  }
+}

Sources/SwiftFormat/PrettyPrint/PrettyPrint.swift

@@ -501,7 +501,7 @@ public class PrettyPrinter {
     case .commaDelimitedRegionStart:
       commaDelimitedRegionStack.append(openCloseBreakCompensatingLineNumber)
 
-    case .commaDelimitedRegionEnd(let hasTrailingComma, let isSingleElement):
+    case .commaDelimitedRegionEnd(let isCollection, let hasTrailingComma, let isSingleElement):
       guard let startLineNumber = commaDelimitedRegionStack.popLast() else {
         fatalError("Found trailing comma end with no corresponding start.")
       }
@@ -511,17 +511,21 @@ public class PrettyPrinter {
       // types) from a literal (where the elements are the contents of a collection instance).
       // We never want to add a trailing comma in an initializer so we disable trailing commas on
       // single element collections.
-      let shouldHaveTrailingComma =
-        startLineNumber != openCloseBreakCompensatingLineNumber && !isSingleElement
-        && configuration.multiElementCollectionTrailingCommas
-      if shouldHaveTrailingComma && !hasTrailingComma {
-        diagnose(.addTrailingComma, category: .trailingComma)
-      } else if !shouldHaveTrailingComma && hasTrailingComma {
-        diagnose(.removeTrailingComma, category: .trailingComma)
-      }
+      if let shouldHandleCommaDelimitedRegion = shouldHandleCommaDelimitedRegion(isCollection: isCollection) {
+        let shouldHaveTrailingComma =
+          startLineNumber != openCloseBreakCompensatingLineNumber && !isSingleElement
+          && shouldHandleCommaDelimitedRegion
+        if shouldHaveTrailingComma && !hasTrailingComma {
+          diagnose(.addTrailingComma, category: .trailingComma)
+        } else if !shouldHaveTrailingComma && hasTrailingComma {
+          diagnose(.removeTrailingComma, category: .trailingComma)
+        }
 
-      let shouldWriteComma = whitespaceOnly ? hasTrailingComma : shouldHaveTrailingComma
-      if shouldWriteComma {
+        let shouldWriteComma = whitespaceOnly ? hasTrailingComma : shouldHaveTrailingComma
+        if shouldWriteComma {
+          outputBuffer.write(",")
+        }
+      } else if hasTrailingComma {
         outputBuffer.write(",")
       }
 
@@ -686,15 +690,19 @@ public class PrettyPrinter {
       case .commaDelimitedRegionStart:
         lengths.append(0)
 
-      case .commaDelimitedRegionEnd(_, let isSingleElement):
+      case .commaDelimitedRegionEnd(let isCollection, _, let isSingleElement):
         // The token's length is only necessary when a comma will be printed, but it's impossible to
         // know at this point whether the region-start token will be on the same line as this token.
         // Without adding this length to the total, it would be possible for this comma to be
         // printed in column `maxLineLength`. Unfortunately, this can cause breaks to fire
         // unnecessarily when the enclosed tokens comma would fit within `maxLineLength`.
-        let length = isSingleElement ? 0 : 1
-        total += length
-        lengths.append(length)
+        if shouldHandleCommaDelimitedRegion(isCollection: isCollection) == true {
+          let length = isSingleElement ? 0 : 1
+          total += length
+          lengths.append(length)
+        } else {
+          lengths.append(0)
+        }
 
       case .enableFormatting, .disableFormatting:
         // no effect on length calculations
@@ -723,6 +731,19 @@ public class PrettyPrinter {
     return outputBuffer.output
   }
 
+  /// Returns whether trailing comma insertion or removal should be performed for the given comma-delimited region,
+  /// or `nil` to keep as written.
+  private func shouldHandleCommaDelimitedRegion(isCollection: Bool) -> Bool? {
+    switch configuration.multilineTrailingCommaBehavior {
+    case .alwaysUsed:
+      return true
+    case .neverUsed:
+      return false
+    case .keptAsWritten:
+      return isCollection ? configuration.multiElementCollectionTrailingCommas : nil
+    }
+  }
+
   /// Used to track the indentation level for the debug token stream output.
   var debugIndent: [Indent] = []
 

Sources/SwiftFormat/PrettyPrint/Token.swift

@@ -194,7 +194,7 @@ enum Token {
 
   /// Marks the end of a comma delimited collection, where a trailing comma should be inserted
   /// if and only if the collection spans multiple lines and has multiple elements.
-  case commaDelimitedRegionEnd(hasTrailingComma: Bool, isSingleElement: Bool)
+  case commaDelimitedRegionEnd(isCollection: Bool, hasTrailingComma: Bool, isSingleElement: Bool)
 
   /// Starts a scope where `contextual` breaks have consistent behavior.
   case contextualBreakingStart

Sources/SwiftFormat/PrettyPrint/TokenStreamCreator.swift

@@ -922,9 +922,7 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
   }
 
   override func visit(_ node: LabeledExprListSyntax) -> SyntaxVisitorContinueKind {
-    // Intentionally do nothing here. Since `TupleExprElement`s are used both in tuple expressions
-    // and function argument lists, which need to be formatted, differently, those nodes manually
-    // loop over the nodes and arrange them in those contexts.
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
     return .visitChildren
   }
 
@@ -967,18 +965,7 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
       }
     }
 
-    if let lastElement = node.last {
-      if let trailingComma = lastElement.trailingComma {
-        ignoredTokens.insert(trailingComma)
-      }
-      before(node.first?.firstToken(viewMode: .sourceAccurate), tokens: .commaDelimitedRegionStart)
-      let endToken =
-        Token.commaDelimitedRegionEnd(
-          hasTrailingComma: lastElement.trailingComma != nil,
-          isSingleElement: node.first == lastElement
-        )
-      after(lastElement.expression.lastToken(viewMode: .sourceAccurate), tokens: [endToken])
-    }
+    markCommaDelimitedRegion(node, isCollectionLiteral: true)
     return .visitChildren
   }
 
@@ -1011,18 +998,7 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
       }
     }
 
-    if let lastElement = node.last {
-      if let trailingComma = lastElement.trailingComma {
-        ignoredTokens.insert(trailingComma)
-      }
-      before(node.first?.firstToken(viewMode: .sourceAccurate), tokens: .commaDelimitedRegionStart)
-      let endToken =
-        Token.commaDelimitedRegionEnd(
-          hasTrailingComma: lastElement.trailingComma != nil,
-          isSingleElement: node.first == node.last
-        )
-      after(lastElement.lastToken(viewMode: .sourceAccurate), tokens: endToken)
-    }
+    markCommaDelimitedRegion(node, isCollectionLiteral: true)
     return .visitChildren
   }
 
@@ -1291,6 +1267,11 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     return .visitChildren
   }
 
+  override func visit(_ node: ClosureCaptureListSyntax) -> SyntaxVisitorContinueKind {
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
+    return .visitChildren
+  }
+
   override func visit(_ node: ClosureCaptureSyntax) -> SyntaxVisitorContinueKind {
     before(node.firstToken(viewMode: .sourceAccurate), tokens: .open)
     after(node.specifier?.lastToken(viewMode: .sourceAccurate), tokens: .break)
@@ -1405,6 +1386,11 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     return .visitChildren
   }
 
+  override func visit(_ node: EnumCaseParameterListSyntax) -> SyntaxVisitorContinueKind {
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
+    return .visitChildren
+  }
+
   override func visit(_ node: FunctionParameterClauseSyntax) -> SyntaxVisitorContinueKind {
     // Prioritize keeping ") throws -> <return_type>" together. We can only do this if the function
     // has arguments.
@@ -1417,6 +1403,11 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     return .visitChildren
   }
 
+  override func visit(_ node: FunctionParameterListSyntax) -> SyntaxVisitorContinueKind {
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
+    return .visitChildren
+  }
+
   override func visit(_ node: ClosureParameterSyntax) -> SyntaxVisitorContinueKind {
     before(node.firstToken(viewMode: .sourceAccurate), tokens: .open)
     arrangeAttributeList(node.attributes)
@@ -1722,6 +1713,11 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     return .visitChildren
   }
 
+  override func visit(_ node: GenericParameterListSyntax) -> SyntaxVisitorContinueKind {
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
+    return .visitChildren
+  }
+
   override func visit(_ node: PrimaryAssociatedTypeClauseSyntax) -> SyntaxVisitorContinueKind {
     after(node.leftAngle, tokens: .break(.open, size: 0), .open(argumentListConsistency()))
     before(node.rightAngle, tokens: .break(.close, size: 0), .close)
@@ -1772,6 +1768,11 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     return .visitChildren
   }
 
+  override func visit(_ node: TuplePatternElementListSyntax) -> SyntaxVisitorContinueKind {
+    markCommaDelimitedRegion(node, isCollectionLiteral: false)
+    return .visitChildren
+  }
+
   override func visit(_ node: TryExprSyntax) -> SyntaxVisitorContinueKind {
     before(
       node.expression.firstToken(viewMode: .sourceAccurate),
@@ -4283,6 +4284,32 @@ fileprivate final class TokenStreamCreator: SyntaxVisitor {
     let hasCompoundExpression = !expr.is(DeclReferenceExprSyntax.self)
     return (hasCompoundExpression, false)
   }
+
+  /// Marks a comma-delimited region for the given list, inserting start/end tokens
+  /// and recording the last element’s trailing comma (if any) to be ignored.
+  ///
+  /// - Parameters:
+  ///   - node: The comma-separated list syntax node.
+  ///   - isCollectionLiteral: Indicates whether the list should be treated as a collection literal during formatting.
+  ///     If `true`, the list is affected by the `multiElementCollectionTrailingCommas` configuration.
+  private func markCommaDelimitedRegion<Node: CommaSeparatedListSyntaxProtocol>(
+    _ node: Node,
+    isCollectionLiteral: Bool
+  ) {
+    if let lastElement = node.last {
+      if let trailingComma = lastElement.trailingComma {
+        ignoredTokens.insert(trailingComma)
+      }
+      before(node.first?.firstToken(viewMode: .sourceAccurate), tokens: .commaDelimitedRegionStart)
+      let endToken =
+        Token.commaDelimitedRegionEnd(
+          isCollection: isCollectionLiteral,
+          hasTrailingComma: lastElement.trailingComma != nil,
+          isSingleElement: node.first == lastElement
+        )
+      after(node.lastNodeForTrailingComma?.lastToken(viewMode: .sourceAccurate), tokens: [endToken])
+    }
+  }
 }
 
 private func isNestedInPostfixIfConfig(node: Syntax) -> Bool {