Support parsing of lifetime dependence specifiers

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/KeywordSpec.swift

@@ -108,7 +108,9 @@ public enum Keyword: CaseIterable {
   case _Class
   case _compilerInitialized
   case _const
+  case _consume
   case _consuming
+  case _copy
   case _documentation
   case _dynamicReplacement
   case _effects
@@ -119,6 +121,7 @@ public enum Keyword: CaseIterable {
   case _local
   case _modify
   case _move
+  case _mutate
   case _mutating
   case _NativeClass
   case _NativeRefCountedObject
@@ -328,6 +331,8 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("_backDeploy")
     case ._borrow:
       return KeywordSpec("_borrow")
+    case ._borrowing:
+      return KeywordSpec("_borrowing", experimentalFeature: .referenceBindings, or: .borrowingSwitch)
     case ._BridgeObject:
       return KeywordSpec("_BridgeObject")
     case ._cdecl:
@@ -338,6 +343,12 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("_compilerInitialized")
     case ._const:
       return KeywordSpec("_const")
+    case ._consume:
+      return KeywordSpec("_consume", experimentalFeature: .nonescapableTypes)
+    case ._consuming:
+      return KeywordSpec("_consuming", experimentalFeature: .referenceBindings)
+    case ._copy:
+      return KeywordSpec("_copy", experimentalFeature: .nonescapableTypes)
     case ._documentation:
       return KeywordSpec("_documentation")
     case ._dynamicReplacement:
@@ -358,6 +369,10 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("_modify")
     case ._move:
       return KeywordSpec("_move")
+    case ._mutate:
+      return KeywordSpec("_mutate", experimentalFeature: .nonescapableTypes)
+    case ._mutating:
+      return KeywordSpec("_mutating", experimentalFeature: .referenceBindings)
     case ._NativeClass:
       return KeywordSpec("_NativeClass")
     case ._NativeRefCountedObject:
@@ -743,12 +758,6 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("wrt")
     case .yield:
       return KeywordSpec("yield")
-    case ._borrowing:
-      return KeywordSpec("_borrowing", experimentalFeature: .referenceBindings, or: .borrowingSwitch)
-    case ._consuming:
-      return KeywordSpec("_consuming", experimentalFeature: .referenceBindings)
-    case ._mutating:
-      return KeywordSpec("_mutating", experimentalFeature: .referenceBindings)
     }
   }
 }

CodeGeneration/Sources/SyntaxSupport/SyntaxNodeKind.swift

@@ -99,8 +99,8 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case dictionaryExpr
   case dictionaryType
   case differentiabilityArgument
-  case differentiabilityArguments
   case differentiabilityArgumentList
+  case differentiabilityArguments
   case differentiabilityWithRespectToArgument
   case differentiableAttributeArguments
   case discardAssignmentExpr
@@ -182,6 +182,9 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case labeledSpecializeArgument
   case labeledStmt
   case layoutRequirement
+  case lifetimeSpecifierArgument
+  case lifetimeSpecifierArgumentList
+  case lifetimeTypeSpecifier
   case macroDecl
   case macroExpansionDecl
   case macroExpansionExpr
@@ -244,14 +247,15 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case returnStmt
   case sameTypeRequirement
   case sequenceExpr
+  case simpleTypeSpecifier
+  case simpleStringLiteralExpr
+  case simpleStringLiteralSegmentList
   case someOrAnyType
   case sourceFile
   case specializeAttributeArgumentList
   case specializeAvailabilityArgument
   case specializeTargetFunctionArgument
   case stmt
-  case simpleStringLiteralExpr
-  case simpleStringLiteralSegmentList
   case stringLiteralExpr
   case stringLiteralSegmentList
   case stringSegment
@@ -286,6 +290,7 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case typeExpr
   case typeInitializerClause
   case typeSpecifier
+  case lifetimeSpecifierArguments
   case typeSpecifierList
   case unavailableFromAsyncAttributeArguments
   case underscorePrivateAttributeArguments
@@ -301,10 +306,10 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case whereClause
   case whileStmt
   case wildcardPattern
-  case yieldStmt
   case yieldedExpression
-  case yieldedExpressionsClause
   case yieldedExpressionList
+  case yieldedExpressionsClause
+  case yieldStmt
 
   // Nodes that have special handling throughout the codebase
 
@@ -407,8 +412,8 @@ public enum SyntaxNodeKind: String, CaseIterable {
     case .derivativeAttributeArguments: return "derivativeRegistrationAttributeArguments"
     case .designatedType: return "designatedTypeElement"
     case .differentiabilityArgument: return "differentiabilityParam"
-    case .differentiabilityArguments: return "differentiabilityParams"
     case .differentiabilityArgumentList: return "differentiabilityParamList"
+    case .differentiabilityArguments: return "differentiabilityParams"
     case .differentiabilityWithRespectToArgument: return "differentiabilityParamsClause"
     case .documentationAttributeArgumentList: return "documentationAttributeArguments"
     case .dynamicReplacementAttributeArguments: return "dynamicReplacementArguments"
@@ -442,6 +447,7 @@ public enum SyntaxNodeKind: String, CaseIterable {
     case .precedenceGroupName: return "precedenceGroupNameElement"
     case .repeatStmt: return "repeatWhileStmt"
     case .someOrAnyType: return "constrainedSugarType"
+    case .simpleTypeSpecifier: return "typeSpecifier"
     case .specializeAttributeArgumentList: return "specializeAttributeSpecList"
     case .specializeAvailabilityArgument: return "availabilityEntry"
     case .specializeTargetFunctionArgument: return "targetFunctionEntry"
@@ -453,8 +459,8 @@ public enum SyntaxNodeKind: String, CaseIterable {
     case .typeAliasDecl: return "typealiasDecl"
     case .unavailableFromAsyncAttributeArguments: return "unavailableFromAsyncArguments"
     case .yieldedExpression: return "yieldExprListElement"
-    case .yieldedExpressionsClause: return "yieldList"
     case .yieldedExpressionList: return "yieldExprList"
+    case .yieldedExpressionsClause: return "yieldList"
     default: return nil
     }
   }

CodeGeneration/Sources/SyntaxSupport/TypeNodes.swift

@@ -496,9 +496,108 @@ public let TYPE_NODES: [Node] = [
   ),
 
   Node(
-    kind: .typeSpecifier,
+    kind: .lifetimeSpecifierArgument,
     base: .syntax,
+    experimentalFeature: .nonescapableTypes,
     nameForDiagnostics: nil,
+    documentation: """
+      A single argument that can be added to a lifetime specifier like `borrow`, `mutate`, `consume` or `copy`.
+
+      ### Example
+      `data` in `func foo(data: Array<Item>) -> borrow(data) ComplexReferenceType`
+      """,
+    traits: [
+      "WithTrailingComma"
+    ],
+    children: [
+      Child(
+        name: "parameter",
+        kind: .token(choices: [.token(.identifier), .keyword(.self), .token(.integerLiteral)]),
+        nameForDiagnostics: "parameter reference",
+        documentation: """
+          The parameter on which the lifetime of this type depends. 
+
+          This can be an identifier referring to an external parameter name, an integer literal to refer to an unnamed
+          parameter or `self` if the type's lifetime depends on the object the method is called on.
+          """
+      ),
+      Child(
+        name: "trailingComma",
+        kind: .token(choices: [.token(.comma)]),
+        isOptional: true
+      ),
+    ]
+  ),
+
+  Node(
+    kind: .lifetimeSpecifierArgumentList,
+    base: .syntaxCollection,
+    experimentalFeature: .nonescapableTypes,
+    nameForDiagnostics: nil,
+    elementChoices: [.lifetimeSpecifierArgument]
+  ),
+
+  Node(
+    kind: .lifetimeSpecifierArguments,
+    base: .syntax,
+    experimentalFeature: .nonescapableTypes,
+    nameForDiagnostics: nil,
+    documentation: """
+      An optional argument passed to a type parameter.
+
+      ### Example
+      `borrow(data)` in `func foo(data: Array<Item>) -> borrow(data) ComplexReferenceType`
+      """,
+    traits: [
+      "Parenthesized"
+    ],
+    children: [
+      Child(
+        name: "leftParen",
+        kind: .token(choices: [.token(.leftParen)])
+      ),
+      Child(
+        name: "arguments",
+        kind: .collection(kind: .lifetimeSpecifierArgumentList, collectionElementName: "Arguments"),
+        documentation: """
+          The function parameters that the lifetime of the annotated type depends on.
+          """
+      ),
+      Child(
+        name: "rightParen",
+        kind: .token(choices: [.token(.rightParen)])
+      ),
+    ]
+  ),
+
+  Node(
+    kind: .lifetimeTypeSpecifier,
+    base: .syntax,
+    experimentalFeature: .nonescapableTypes,
+    nameForDiagnostics: "lifetime specifier",
+    documentation: "A specifier that specifies function parameter on whose lifetime a type depends",
+    children: [
+      Child(
+        name: "specifier",
+        kind: .token(choices: [
+          .keyword(._copy),
+          .keyword(._consume),
+          .keyword(._borrow),
+          .keyword(._mutate),
+        ]),
+        documentation: "The specifier token that's attached to the type."
+      ),
+      Child(
+        name: "arguments",
+        kind: .node(kind: .lifetimeSpecifierArguments)
+      ),
+    ]
+  ),
+
+  Node(
+    kind: .simpleTypeSpecifier,
+    base: .syntax,
+    nameForDiagnostics: "type specifier",
     documentation: "A specifier that can be attached to a type to eg. mark a parameter as `inout` or `consuming`",
     children: [
       Child(
@@ -523,6 +622,6 @@ public let TYPE_NODES: [Node] = [
     kind: .typeSpecifierList,
     base: .syntaxCollection,
     nameForDiagnostics: nil,
-    elementChoices: [.typeSpecifier]
+    elementChoices: [.simpleTypeSpecifier, .lifetimeTypeSpecifier]
   ),
 ]

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift

@@ -53,7 +53,7 @@ let nodesSections: String = {
         }
         return [node.kind.syntaxType.description]
           + node.elementChoices
-          .filter { SYNTAX_NODE_MAP[$0] != nil }
+          .filter { SYNTAX_NODE_MAP[$0] != nil && !SYNTAX_NODE_MAP[$0]!.isExperimental }
           .map(\.syntaxType.description)
           .filter { !handledSyntaxTypes.contains($0) }
       })

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxCollectionsFile.swift

@@ -41,7 +41,12 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
         ) {
           for choiceName in node.elementChoices {
             let choice = SYNTAX_NODE_MAP[choiceName]!
-            DeclSyntax("case `\(choice.varOrCaseName)`(\(choice.kind.syntaxType))")
+            DeclSyntax(
+              """
+              \(choice.apiAttributes())\
+              case `\(choice.varOrCaseName)`(\(choice.kind.syntaxType))
+              """
+            )
           }
 
           try VariableDeclSyntax("public var _syntaxNode: Syntax") {
@@ -60,6 +65,7 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
             if choiceNode.kind.isBase {
               DeclSyntax(
                 """
+                \(choiceNode.apiAttributes())\
                 public init(_ node: some \(choiceNode.kind.protocolType)) {
                   self = .\(choiceNode.varOrCaseName)(\(choiceNode.kind.syntaxType)(node))
                 }
@@ -69,6 +75,7 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
             } else {
               DeclSyntax(
                 """
+                \(choiceNode.apiAttributes())\
                 public init(_ node: \(choiceNode.kind.syntaxType)) {
                   self = .\(choiceNode.varOrCaseName)(node)
                 }

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxNodeCasting.swift

@@ -16,12 +16,14 @@ import SyntaxSupport
 
 @MemberBlockItemListBuilder
 func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlockItemListSyntax {
+  let apiAttributes = SYNTAX_NODE_MAP[syntaxNodeKind]?.apiAttributes() ?? []
   if syntaxNodeKind.isBase {
     DeclSyntax(
       """
       /// Checks if the current syntax node can be cast to the type conforming to the ``\(syntaxNodeKind.protocolType)`` protocol.
       ///
       /// - Returns: `true` if the node can be cast, `false` otherwise.
+      \(apiAttributes)\
       public func `is`<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> Bool {
         return self.as(syntaxType) != nil
       }
@@ -33,6 +35,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
       /// Attempts to cast the current syntax node to the type conforming to the ``\(syntaxNodeKind.protocolType)`` protocol.
       ///
       /// - Returns: An instance of the specialized type, or `nil` if the cast fails.
+      \(apiAttributes)\
       public func `as`<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> S? {
         return S.init(self)
       }
@@ -45,6 +48,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
       ///
       /// - Returns: An instance of the specialized type.
       /// - Warning: This function will crash if the cast is not possible. Use `as` to safely attempt a cast.
+      \(apiAttributes)\
       public func cast<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> S {
         return self.as(S.self)!
       }
@@ -56,6 +60,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
       /// Checks if the current syntax node can be cast to ``\(syntaxNodeKind.syntaxType)``.
       ///
       /// - Returns: `true` if the node can be cast, `false` otherwise.
+      \(apiAttributes)\
       public func `is`(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> Bool {
         return self.as(syntaxType) != nil
       }
@@ -67,6 +72,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
       /// Attempts to cast the current syntax node to ``\(syntaxNodeKind.syntaxType)``.
       ///
       /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``, or `nil` if the cast fails.
+      \(apiAttributes)\
       public func `as`(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType)? {
         return \(syntaxNodeKind.syntaxType).init(self)
       }
@@ -79,6 +85,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
       ///
       /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``.
       /// - Warning: This function will crash if the cast is not possible. Use `as` to safely attempt a cast.
+      \(apiAttributes)\
       public func cast(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType) {
         return self.as(\(syntaxNodeKind.syntaxType).self)!
       }

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntaxbuilder/ResultBuildersFile.swift

@@ -19,9 +19,9 @@ let resultBuildersFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
   DeclSyntax(
     """
     #if swift(>=6)
-    public import SwiftSyntax
+    @_spi(ExperimentalLanguageFeatures) public import SwiftSyntax
     #else
-    import SwiftSyntax
+    @_spi(ExperimentalLanguageFeatures) import SwiftSyntax
     #endif
     """
   )
@@ -48,6 +48,7 @@ let resultBuildersFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
         for elementChoice in node.elementChoices {
           DeclSyntax(
             """
+            \(SYNTAX_NODE_MAP[elementChoice]?.apiAttributes() ?? [])\
             public static func buildExpression(_ expression: \(elementChoice.syntaxType)) -> Component {
               buildExpression(.init(expression))
             }