Make SyntaxCollection conform to RangeReplaceableCollection and remove add* methods on syntax nodes that have a collection as child

Conforming `SyntaxCollection` to `RangeReplaceableCollection` gives it a lot of the functions you know from `Swift.Array`.

And with those methods, we no longer need the `add*` methods on syntax nodes that have a syntax collection as their child.

Author: ahoppen

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SyntaxNodesFile.swift

@@ -203,6 +203,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
               ///                  `\(child.varOrCaseName)` collection.
               /// - returns: A copy of the receiver with the provided `\(raw: childElt)`
               ///            appended to its `\(child.varOrCaseName)` collection.
+              @available(*, deprecated, message: "Use node.\(child.varOrCaseName).append(newElement) instead")
               public func add\(raw: childElt)(_ element: \(raw: childEltType)) -> \(node.kind.syntaxType) {
                 var collection: RawSyntax
                 let arena = SyntaxArena()

Sources/SwiftSyntax/SyntaxCollection.swift

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-public protocol SyntaxCollection: SyntaxProtocol, BidirectionalCollection, MutableCollection where Element: SyntaxProtocol {
+public protocol SyntaxCollection: SyntaxProtocol, BidirectionalCollection, MutableCollection, RangeReplaceableCollection where Element: SyntaxProtocol {
   associatedtype Iterator = SyntaxCollectionIterator<Element>
 
   /// The ``SyntaxKind`` of the syntax node that conforms to ``SyntaxCollection``.
@@ -33,6 +33,11 @@ extension SyntaxCollection {
     self.init(Syntax(data))!
   }
 
+  /// Create an empty ``SyntaCollection`` with no children.
+  public init() {
+    self.init([])
+  }
+
   public init<Children: Sequence>(_ children: Children) where Children.Element == Element {
     let arena = SyntaxArena()
     // Extend the lifetime of children so their arenas don't get destroyed
@@ -89,6 +94,19 @@ extension SyntaxCollection {
     return node.indexInParent
   }
 
+  /// Replace the nodes in `subrange` by `newElements`.
+  public mutating func replaceSubrange(_ subrange: Range<SyntaxChildrenIndex>, with newElements: some Collection<Element>) {
+    // We only access the raw nodes of `newElements` below.
+    // Keep `newElements` alive so their arena doesn't get deallocated.
+    withExtendedLifetime(newElements) {
+      var newLayout = layoutView.formLayoutArray()
+      let layoutRangeLowerBound = (subrange.lowerBound.data?.indexInParent).map(Int.init) ?? newLayout.endIndex
+      let layoutRangeUpperBound = (subrange.upperBound.data?.indexInParent).map(Int.init) ?? newLayout.endIndex
+      newLayout.replaceSubrange(layoutRangeLowerBound..<layoutRangeUpperBound, with: newElements.map { $0.raw })
+      self = replacingLayout(newLayout)
+    }
+  }
+
   /// Creates a new collection by appending the provided syntax element
   /// to the children.
   ///

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxDeclNodes.swift

@@ -127,6 +127,7 @@ public struct ArrayExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `elements` collection.
   /// - returns: A copy of the receiver with the provided `Element`
   ///            appended to its `elements` collection.
+  @available(*, deprecated, message: "Use node.elements.append(newElement) instead")
   public func addElement(_ element: ArrayElementSyntax) -> ArrayExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -1507,6 +1508,7 @@ public struct ClosureExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `statements` collection.
   /// - returns: A copy of the receiver with the provided `Statement`
   ///            appended to its `statements` collection.
+  @available(*, deprecated, message: "Use node.statements.append(newElement) instead")
   public func addStatement(_ element: CodeBlockItemSyntax) -> ClosureExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -2527,6 +2529,7 @@ public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `arguments` collection.
   /// - returns: A copy of the receiver with the provided `Argument`
   ///            appended to its `arguments` collection.
+  @available(*, deprecated, message: "Use node.arguments.append(newElement) instead")
   public func addArgument(_ element: LabeledExprSyntax) -> FunctionCallExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -2605,6 +2608,7 @@ public struct FunctionCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `additionalTrailingClosures` collection.
   /// - returns: A copy of the receiver with the provided `AdditionalTrailingClosure`
   ///            appended to its `additionalTrailingClosures` collection.
+  @available(*, deprecated, message: "Use node.additionalTrailingClosures.append(newElement) instead")
   public func addAdditionalTrailingClosure(_ element: MultipleTrailingClosureElementSyntax) -> FunctionCallExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -3070,6 +3074,7 @@ public struct IfExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `conditions` collection.
   /// - returns: A copy of the receiver with the provided `Condition`
   ///            appended to its `conditions` collection.
+  @available(*, deprecated, message: "Use node.conditions.append(newElement) instead")
   public func addCondition(_ element: ConditionElementSyntax) -> IfExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -3818,6 +3823,7 @@ public struct KeyPathExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `components` collection.
   /// - returns: A copy of the receiver with the provided `KeyPathComponent`
   ///            appended to its `components` collection.
+  @available(*, deprecated, message: "Use node.components.append(newElement) instead")
   public func addKeyPathComponent(_ element: KeyPathComponentSyntax) -> KeyPathExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -4064,6 +4070,7 @@ public struct MacroExpansionExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `arguments` collection.
   /// - returns: A copy of the receiver with the provided `Argument`
   ///            appended to its `arguments` collection.
+  @available(*, deprecated, message: "Use node.arguments.append(newElement) instead")
   public func addArgument(_ element: LabeledExprSyntax) -> MacroExpansionExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -4142,6 +4149,7 @@ public struct MacroExpansionExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `additionalTrailingClosures` collection.
   /// - returns: A copy of the receiver with the provided `AdditionalTrailingClosure`
   ///            appended to its `additionalTrailingClosures` collection.
+  @available(*, deprecated, message: "Use node.additionalTrailingClosures.append(newElement) instead")
   public func addAdditionalTrailingClosure(_ element: MultipleTrailingClosureElementSyntax) -> MacroExpansionExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -5633,6 +5641,7 @@ public struct SequenceExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `elements` collection.
   /// - returns: A copy of the receiver with the provided `Element`
   ///            appended to its `elements` collection.
+  @available(*, deprecated, message: "Use node.elements.append(newElement) instead")
   public func addElement(_ element: ExprSyntax) -> SequenceExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -5825,6 +5834,7 @@ public struct StringLiteralExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `segments` collection.
   /// - returns: A copy of the receiver with the provided `Segment`
   ///            appended to its `segments` collection.
+  @available(*, deprecated, message: "Use node.segments.append(newElement) instead")
   public func addSegment(_ element: Syntax) -> StringLiteralExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -6059,6 +6069,7 @@ public struct SubscriptCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `arguments` collection.
   /// - returns: A copy of the receiver with the provided `Argument`
   ///            appended to its `arguments` collection.
+  @available(*, deprecated, message: "Use node.arguments.append(newElement) instead")
   public func addArgument(_ element: LabeledExprSyntax) -> SubscriptCallExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -6137,6 +6148,7 @@ public struct SubscriptCallExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `additionalTrailingClosures` collection.
   /// - returns: A copy of the receiver with the provided `AdditionalTrailingClosure`
   ///            appended to its `additionalTrailingClosures` collection.
+  @available(*, deprecated, message: "Use node.additionalTrailingClosures.append(newElement) instead")
   public func addAdditionalTrailingClosure(_ element: MultipleTrailingClosureElementSyntax) -> SubscriptCallExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -6431,6 +6443,7 @@ public struct SwitchExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `cases` collection.
   /// - returns: A copy of the receiver with the provided `Case`
   ///            appended to its `cases` collection.
+  @available(*, deprecated, message: "Use node.cases.append(newElement) instead")
   public func addCase(_ element: Syntax) -> SwitchExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()
@@ -6960,6 +6973,7 @@ public struct TupleExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   ///                  `elements` collection.
   /// - returns: A copy of the receiver with the provided `Element`
   ///            appended to its `elements` collection.
+  @available(*, deprecated, message: "Use node.elements.append(newElement) instead")
   public func addElement(_ element: LabeledExprSyntax) -> TupleExprSyntax {
     var collection: RawSyntax
     let arena = SyntaxArena()