Allow putting garbage nodes in between any two children of a Syntax node

Sources/SwiftSyntax/SyntaxAnyVisitor.swift.gyb

@@ -40,9 +40,6 @@
 ///       }
 ///
 open class SyntaxAnyVisitor: SyntaxVisitor {
-  /// Visiting `UnknownSyntax` specifically.
-  ///   - Parameter node: the node we are visiting.
-  ///   - Returns: how should we continue visiting.
   open func visitAny(_ node: Syntax) -> SyntaxVisitorContinueKind {
     return .visitChildren
   }

Sources/SwiftSyntax/SyntaxBuilders.swift.gyb

@@ -34,7 +34,9 @@ public struct ${Builder} {
     Array<RawSyntax?>(repeating: nil, count: ${len(node.children)})
 
   internal init() {}
-%     for child in node.children:
+%     # SyntaxBuilder doesn't support adding garbage nodes at the moment
+%     # This could be added in the future, if needed.
+%     for child in node.non_garbage_children:
 %       child_node = NODE_MAP.get(child.syntax_kind)
 %       if child_node and child_node.is_syntax_collection():
 %         child_elt = child.collection_element_name

Sources/SwiftSyntax/SyntaxFactory.swift.gyb

@@ -52,10 +52,18 @@ public enum SyntaxFactory {
 %   elif node.children:
 %     child_params = []
 %     for child in node.children:
-%         param_type = child.type_name
-%         if child.is_optional:
-%            param_type = param_type + "?"
+%       param_type = child.type_name
+%       if child.is_optional:
+%          param_type = param_type + "?"
+%       end
+%       if child.is_garbage_nodes():
+%         # It would be nice if we could label all of these arguments 'garbage'.
+%         # But if we do this, we hit https://github.com/apple/swift/issues/60274.
+%         child_params.append("_ %s: %s = nil" % (child.swift_name, param_type))
+%       else:
 %         child_params.append("%s: %s" % (child.swift_name, param_type))
+%       end
+%     end
 %     child_params = ', '.join(child_params)
   public static func make${node.syntax_kind}(${child_params}) -> ${node.name} {
     let layout: [RawSyntax?] = [

Sources/SwiftSyntax/SyntaxNodes.swift.gyb.template

@@ -115,7 +115,9 @@ public struct ${node.name}: ${base_type}Protocol, SyntaxHashable {
 %       # ===============
 %       # Adding children
 %       # ===============
-%       if child_node and child_node.is_syntax_collection():
+%       # We don't currently support adding elements to a specific garbage collection.
+%       # If needed, this could be added in the future, but for now withGarbage should be sufficient.
+%       if child_node and child_node.is_syntax_collection() and not child.is_garbage_nodes():
 %         child_elt = child.collection_element_name
 %         child_elt_type = child_node.collection_element_type
 %         if not child_elt:

Sources/SwiftSyntax/SyntaxTreeViewMode.swift

@@ -35,7 +35,7 @@ public enum SyntaxTreeViewMode {
     case .sourceAccurate:
       return node.presence == .present
     case .fixedUp:
-      return true
+      return node.kind != .garbageNodes
     case ._all:
       return true
     }

Sources/SwiftSyntax/Trivia.swift.gyb

@@ -177,6 +177,26 @@ extension Trivia: ExpressibleByArrayLiteral {
   }
 }
 
+extension Trivia: TextOutputStreamable {
+  /// Prints the provided trivia as they would be written in a source file.
+  ///
+  /// - Parameter stream: The stream to which to print the trivia.
+  public func write<Target>(to target: inout Target)
+    where Target: TextOutputStream {
+      for piece in pieces {
+        piece.write(to: &target)
+      }
+  }
+}
+
+extension Trivia: CustomStringConvertible {
+  public var description: String {
+    var description = ""
+    self.write(to: &description)
+    return description
+  }
+}
+
 /// Concatenates two collections of `Trivia` into one collection.
 public func +(lhs: Trivia, rhs: Trivia) -> Trivia {
   return Trivia(pieces: lhs.pieces + rhs.pieces)

Sources/SwiftSyntax/gyb_generated/Misc.swift

@@ -103,6 +103,12 @@ extension SyntaxNode {
     return CodeBlockSyntax(asSyntaxData)
   }
 
+  public var isGarbageNodes: Bool { return raw.kind == .garbageNodes }
+  public var asGarbageNodes: GarbageNodesSyntax? {
+    guard isGarbageNodes else { return nil }
+    return GarbageNodesSyntax(asSyntaxData)
+  }
+
   public var isInOutExpr: Bool { return raw.kind == .inOutExpr }
   public var asInOutExpr: InOutExprSyntax? {
     guard isInOutExpr else { return nil }
@@ -1601,6 +1607,8 @@ extension Syntax {
       return node
     case .codeBlock(let node):
       return node
+    case .garbageNodes(let node):
+      return node
     case .inOutExpr(let node):
       return node
     case .poundColumnExpr(let node):

Sources/SwiftSyntax/gyb_generated/SyntaxAnyVisitor.swift

@@ -35,9 +35,6 @@
 ///       }
 ///
 open class SyntaxAnyVisitor: SyntaxVisitor {
-  /// Visiting `UnknownSyntax` specifically.
-  ///   - Parameter node: the node we are visiting.
-  ///   - Returns: how should we continue visiting.
   open func visitAny(_ node: Syntax) -> SyntaxVisitorContinueKind {
     return .visitChildren
   }
@@ -162,6 +159,13 @@ open class SyntaxAnyVisitor: SyntaxVisitor {
   override open func visitPost(_ node: CodeBlockSyntax) {
     visitAnyPost(node._syntaxNode)
   }
+  override open func visit(_ node: GarbageNodesSyntax) -> SyntaxVisitorContinueKind {
+    return visitAny(node._syntaxNode)
+  }
+
+  override open func visitPost(_ node: GarbageNodesSyntax) {
+    visitAnyPost(node._syntaxNode)
+  }
   override open func visit(_ node: InOutExprSyntax) -> SyntaxVisitorContinueKind {
     return visitAny(node._syntaxNode)
   }