support parsing discard in place of _forget

SE-390 concluded with choosing the keyword `discard` rather than
`forget`. This commit begins the process of deprecating the old
keyword on the swift-syntax side.

rdar://108859077

Author: kavon

CodeGeneration/Sources/SyntaxSupport/KeywordSpec.swift

@@ -134,7 +134,8 @@ public let KEYWORDS: [KeywordSpec] = [
   KeywordSpec("fileprivate", isLexerClassified: true, requiresTrailingSpace: true),
   KeywordSpec("final"),
   KeywordSpec("for", isLexerClassified: true, requiresTrailingSpace: true),
-  KeywordSpec("_forget"),
+  KeywordSpec("_forget"),  // NOTE: support for deprecated _forget
+  KeywordSpec("discard"),
   KeywordSpec("forward"),
   KeywordSpec("func", isLexerClassified: true, requiresTrailingSpace: true),
   KeywordSpec("get"),

CodeGeneration/Sources/SyntaxSupport/StmtNodes.swift

@@ -333,15 +333,18 @@ public let STMT_NODES: [Node] = [
     ]
   ),
 
-  // forget-stmt -> 'forget' expr ';'?
+  // discard-stmt -> 'discard' expr ';'?
   Node(
-    name: "ForgetStmt",
-    nameForDiagnostics: "'forget' statement",
+    name: "DiscardStmt",
+    nameForDiagnostics: "'discard' statement",
     kind: "Stmt",
     children: [
       Child(
-        name: "ForgetKeyword",
-        kind: .token(choices: [.keyword(text: "_forget")])
+        name: "DiscardKeyword",
+        kind: .token(choices: [
+          .keyword(text: "_forget"),  // NOTE: support for deprecated _forget
+          .keyword(text: "discard"),
+        ])
       ),
       Child(
         name: "Expression",

Sources/SwiftParser/Statements.swift

@@ -55,7 +55,7 @@ extension Parser {
   ///     statement → control-transfer-statement ';'?
   ///     statement → defer-statement ';'?
   ///     statement → do-statement ';'?
-  ///     statement → forget-statement ';'?
+  ///     statement → discard-statement ';'?
   ///
   ///     loop-statement → for-in-statement
   ///     loop-statement → while-statement
@@ -124,8 +124,10 @@ extension Parser {
       return label(self.parseContinueStatement(continueHandle: handle), with: optLabel)
     case (.fallthroughKeyword, let handle)?:
       return label(self.parseFallthroughStatement(fallthroughHandle: handle), with: optLabel)
-    case (.forgetKeyword, let handle)?:
-      return label(self.parseForgetStatement(forgetHandle: handle), with: optLabel)
+    case (.forgetKeyword, let handle)?:  // NOTE: support for deprecated _forget
+      fallthrough
+    case (.discardKeyword, let handle)?:
+      return label(self.parseDiscardStatement(discardHandle: handle), with: optLabel)
     case (.returnKeyword, let handle)?:
       return label(self.parseReturnStatement(returnHandle: handle), with: optLabel)
     case (.throwKeyword, let handle)?:
@@ -393,22 +395,24 @@ extension Parser {
   }
 }
 
-// MARK: Forget Statements
+// MARK: Discard Statements
 
 extension Parser {
-  /// Parse a forget statement.
+  /// Parse a discard statement.
   ///
   /// Grammar
   /// =======
   ///
-  ///     forget-statement → 'forget' expression
+  ///     discard-statement → 'discard' expression
+  ///
+  /// where expression's first token is an identifier.
   @_spi(RawSyntax)
-  public mutating func parseForgetStatement(forgetHandle: RecoveryConsumptionHandle) -> RawForgetStmtSyntax {
-    let (unexpectedBeforeForgetKeyword, forgetKeyword) = self.eat(forgetHandle)
+  public mutating func parseDiscardStatement(discardHandle: RecoveryConsumptionHandle) -> RawDiscardStmtSyntax {
+    let (unexpectedBeforeDiscardKeyword, discardKeyword) = self.eat(discardHandle)
     let expr = self.parseExpression()
-    return RawForgetStmtSyntax(
-      unexpectedBeforeForgetKeyword,
-      forgetKeyword: forgetKeyword,
+    return RawDiscardStmtSyntax(
+      unexpectedBeforeDiscardKeyword,
+      discardKeyword: discardKeyword,
       expression: expr,
       arena: self.arena
     )
@@ -1009,22 +1013,24 @@ extension Parser.Lookahead {
         // yield statement of some singular expression.
         return !self.peek().isAtStartOfLine
       }
-    case .forgetKeyword?:
+    case .forgetKeyword?:  // NOTE: support for deprecated _forget
+      fallthrough
+    case .discardKeyword?:
       let next = peek()
-      // The thing to be forgotten must be on the same line as `forget`.
+      // The thing to be discarded must be on the same line as `discard`.
       if next.isAtStartOfLine {
         return false
       }
       switch next.rawTokenKind {
       case .identifier, .keyword:
         // Since some identifiers like "self" are classified as keywords,
-        // we want to recognize those too, to handle "forget self". We also
+        // we want to recognize those too, to handle "discard self". We also
         // accept any identifier since we want to emit a nice error message
         // later on during type checking.
         return true
       default:
-        // any other token following "forget" means it's not the statement.
-        // For example, could be the function call "forget()".
+        // any other token following "discard" means it's not the statement.
+        // For example, could be the function call "discard()".
         return false
       }
     case nil:

Sources/SwiftParser/TokenSpecSet.swift

@@ -80,7 +80,8 @@ enum CanBeStatementStart: TokenSpecSet {
   case doKeyword
   case fallthroughKeyword
   case forKeyword
-  case forgetKeyword
+  case forgetKeyword  // NOTE: support for deprecated _forget
+  case discardKeyword
   case guardKeyword
   case ifKeyword
   case repeatKeyword
@@ -99,6 +100,7 @@ enum CanBeStatementStart: TokenSpecSet {
     case TokenSpec(.fallthrough): self = .fallthroughKeyword
     case TokenSpec(.for): self = .forKeyword
     case TokenSpec(._forget): self = .forgetKeyword
+    case TokenSpec(.discard): self = .discardKeyword
     case TokenSpec(.guard): self = .guardKeyword
     case TokenSpec(.if): self = .ifKeyword
     case TokenSpec(.repeat): self = .repeatKeyword
@@ -120,6 +122,7 @@ enum CanBeStatementStart: TokenSpecSet {
     case .fallthroughKeyword: return .keyword(.fallthrough)
     case .forKeyword: return .keyword(.for)
     case .forgetKeyword: return TokenSpec(._forget, recoveryPrecedence: .stmtKeyword)
+    case .discardKeyword: return TokenSpec(.discard, recoveryPrecedence: .stmtKeyword)
     case .guardKeyword: return .keyword(.guard)
     case .ifKeyword: return .keyword(.if)
     case .repeatKeyword: return .keyword(.repeat)

Sources/SwiftParserDiagnostics/generated/SyntaxKindNameForDiagnostics.swift

@@ -133,6 +133,8 @@ extension SyntaxKind {
       return "differentiability parameters"
     case .differentiableAttributeArguments:
       return "'@differentiable' arguments"
+    case .discardStmt:
+      return "'discard' statement"
     case .doStmt:
       return "'do' statement"
     case .documentationAttributeArgument:
@@ -173,8 +175,6 @@ extension SyntaxKind {
       return "'for' statement"
     case .forcedValueExpr:
       return "force unwrap"
-    case .forgetStmt:
-      return "'forget' statement"
     case .functionCallExpr:
       return "function call"
     case .functionDecl:

Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md

@@ -153,11 +153,11 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 - <doc:SwiftSyntax/BreakStmtSyntax>
 - <doc:SwiftSyntax/ContinueStmtSyntax>
 - <doc:SwiftSyntax/DeferStmtSyntax>
+- <doc:SwiftSyntax/DiscardStmtSyntax>
 - <doc:SwiftSyntax/DoStmtSyntax>
 - <doc:SwiftSyntax/ExpressionStmtSyntax>
 - <doc:SwiftSyntax/FallthroughStmtSyntax>
 - <doc:SwiftSyntax/ForInStmtSyntax>
-- <doc:SwiftSyntax/ForgetStmtSyntax>
 - <doc:SwiftSyntax/GuardStmtSyntax>
 - <doc:SwiftSyntax/LabeledStmtSyntax>
 - <doc:SwiftSyntax/RepeatWhileStmtSyntax>

Sources/SwiftSyntax/generated/ChildNameForKeyPath.swift

@@ -1003,6 +1003,16 @@ public func childName(_ keyPath: AnyKeyPath) -> String? {
     return "wildcard"
   case \DiscardAssignmentExprSyntax.unexpectedAfterWildcard:
     return "unexpectedAfterWildcard"
+  case \DiscardStmtSyntax.unexpectedBeforeDiscardKeyword:
+    return "unexpectedBeforeDiscardKeyword"
+  case \DiscardStmtSyntax.discardKeyword:
+    return "discardKeyword"
+  case \DiscardStmtSyntax.unexpectedBetweenDiscardKeywordAndExpression:
+    return "unexpectedBetweenDiscardKeywordAndExpression"
+  case \DiscardStmtSyntax.expression:
+    return "expression"
+  case \DiscardStmtSyntax.unexpectedAfterExpression:
+    return "unexpectedAfterExpression"
   case \DoStmtSyntax.unexpectedBeforeDoKeyword:
     return "unexpectedBeforeDoKeyword"
   case \DoStmtSyntax.doKeyword:
@@ -1317,16 +1327,6 @@ public func childName(_ keyPath: AnyKeyPath) -> String? {
     return "exclamationMark"
   case \ForcedValueExprSyntax.unexpectedAfterExclamationMark:
     return "unexpectedAfterExclamationMark"
-  case \ForgetStmtSyntax.unexpectedBeforeForgetKeyword:
-    return "unexpectedBeforeForgetKeyword"
-  case \ForgetStmtSyntax.forgetKeyword:
-    return "forgetKeyword"
-  case \ForgetStmtSyntax.unexpectedBetweenForgetKeywordAndExpression:
-    return "unexpectedBetweenForgetKeywordAndExpression"
-  case \ForgetStmtSyntax.expression:
-    return "expression"
-  case \ForgetStmtSyntax.unexpectedAfterExpression:
-    return "unexpectedAfterExpression"
   case \FunctionCallExprSyntax.unexpectedBeforeCalledExpression:
     return "unexpectedBeforeCalledExpression"
   case \FunctionCallExprSyntax.calledExpression:

Sources/SwiftSyntax/generated/Keyword.swift

@@ -112,6 +112,7 @@ public enum Keyword: UInt8, Hashable {
   case final
   case `for`
   case _forget
+  case discard
   case forward
   case `func`
   case get
@@ -427,6 +428,8 @@ public enum Keyword: UInt8, Hashable {
         self = .dynamic
       case "_forget":
         self = ._forget
+      case "discard":
+        self = .discard
       case "forward":
         self = .forward
       case "message":
@@ -832,6 +835,7 @@ public enum Keyword: UInt8, Hashable {
       "final", 
       "for", 
       "_forget", 
+      "discard", 
       "forward", 
       "func", 
       "get", 

Sources/SwiftSyntax/generated/SyntaxAnyVisitor.swift

@@ -741,6 +741,14 @@ open class SyntaxAnyVisitor: SyntaxVisitor {
     visitAnyPost(node._syntaxNode)
   }
 
+  override open func visit(_ node: DiscardStmtSyntax) -> SyntaxVisitorContinueKind {
+    return visitAny(node._syntaxNode)
+  }
+  
+  override open func visitPost(_ node: DiscardStmtSyntax) {
+    visitAnyPost(node._syntaxNode)
+  }
+  
   override open func visit(_ node: DoStmtSyntax) -> SyntaxVisitorContinueKind {
     return visitAny(node._syntaxNode)
   }
@@ -933,14 +941,6 @@ open class SyntaxAnyVisitor: SyntaxVisitor {
     visitAnyPost(node._syntaxNode)
   }
 
-  override open func visit(_ node: ForgetStmtSyntax) -> SyntaxVisitorContinueKind {
-    return visitAny(node._syntaxNode)
-  }
-  
-  override open func visitPost(_ node: ForgetStmtSyntax) {
-    visitAnyPost(node._syntaxNode)
-  }
-  
   override open func visit(_ node: FunctionCallExprSyntax) -> SyntaxVisitorContinueKind {
     return visitAny(node._syntaxNode)
   }

Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift

@@ -483,7 +483,7 @@ public struct StmtSyntax: StmtSyntaxProtocol, SyntaxHashable {
 
   public init?<S: SyntaxProtocol>(_ node: S) {
     switch node.raw.kind {
-    case .breakStmt, .continueStmt, .deferStmt, .doStmt, .expressionStmt, .fallthroughStmt, .forInStmt, .forgetStmt, .guardStmt, .labeledStmt, .missingStmt, .repeatWhileStmt, .returnStmt, .throwStmt, .whileStmt, .yieldStmt:
+    case .breakStmt, .continueStmt, .deferStmt, .discardStmt, .doStmt, .expressionStmt, .fallthroughStmt, .forInStmt, .guardStmt, .labeledStmt, .missingStmt, .repeatWhileStmt, .returnStmt, .throwStmt, .whileStmt, .yieldStmt:
       self._syntaxNode = node._syntaxNode
     default:
       return nil
@@ -495,7 +495,7 @@ public struct StmtSyntax: StmtSyntaxProtocol, SyntaxHashable {
   /// is undefined.
   internal init(_ data: SyntaxData) {
     switch data.raw.kind {
-    case .breakStmt, .continueStmt, .deferStmt, .doStmt, .expressionStmt, .fallthroughStmt, .forInStmt, .forgetStmt, .guardStmt, .labeledStmt, .missingStmt, .repeatWhileStmt, .returnStmt, .throwStmt, .whileStmt, .yieldStmt:
+    case .breakStmt, .continueStmt, .deferStmt, .discardStmt, .doStmt, .expressionStmt, .fallthroughStmt, .forInStmt, .guardStmt, .labeledStmt, .missingStmt, .repeatWhileStmt, .returnStmt, .throwStmt, .whileStmt, .yieldStmt:
       break
     default:
       preconditionFailure("Unable to create StmtSyntax from \(data.raw.kind)")
@@ -534,11 +534,11 @@ public struct StmtSyntax: StmtSyntaxProtocol, SyntaxHashable {
           .node(BreakStmtSyntax.self),
           .node(ContinueStmtSyntax.self),
           .node(DeferStmtSyntax.self),
+          .node(DiscardStmtSyntax.self),
           .node(DoStmtSyntax.self),
           .node(ExpressionStmtSyntax.self),
           .node(FallthroughStmtSyntax.self),
           .node(ForInStmtSyntax.self),
-          .node(ForgetStmtSyntax.self),
           .node(GuardStmtSyntax.self),
           .node(LabeledStmtSyntax.self),
           .node(MissingStmtSyntax.self),
@@ -770,6 +770,7 @@ extension Syntax {
           .node(DifferentiabilityParamsSyntax.self),
           .node(DifferentiableAttributeArgumentsSyntax.self),
           .node(DiscardAssignmentExprSyntax.self),
+          .node(DiscardStmtSyntax.self),
           .node(DoStmtSyntax.self),
           .node(DocumentationAttributeArgumentSyntax.self),
           .node(DocumentationAttributeArgumentsSyntax.self),
@@ -794,7 +795,6 @@ extension Syntax {
           .node(FloatLiteralExprSyntax.self),
           .node(ForInStmtSyntax.self),
           .node(ForcedValueExprSyntax.self),
-          .node(ForgetStmtSyntax.self),
           .node(FunctionCallExprSyntax.self),
           .node(FunctionDeclSyntax.self),
           .node(FunctionEffectSpecifiersSyntax.self),

Sources/SwiftSyntax/generated/SyntaxEnum.swift

@@ -102,6 +102,7 @@ public enum SyntaxEnum {
   case differentiabilityParams(DifferentiabilityParamsSyntax)
   case differentiableAttributeArguments(DifferentiableAttributeArgumentsSyntax)
   case discardAssignmentExpr(DiscardAssignmentExprSyntax)
+  case discardStmt(DiscardStmtSyntax)
   case doStmt(DoStmtSyntax)
   case documentationAttributeArgument(DocumentationAttributeArgumentSyntax)
   case documentationAttributeArguments(DocumentationAttributeArgumentsSyntax)
@@ -126,7 +127,6 @@ public enum SyntaxEnum {
   case floatLiteralExpr(FloatLiteralExprSyntax)
   case forInStmt(ForInStmtSyntax)
   case forcedValueExpr(ForcedValueExprSyntax)
-  case forgetStmt(ForgetStmtSyntax)
   case functionCallExpr(FunctionCallExprSyntax)
   case functionDecl(FunctionDeclSyntax)
   case functionEffectSpecifiers(FunctionEffectSpecifiersSyntax)
@@ -465,6 +465,8 @@ public extension Syntax {
       return .differentiableAttributeArguments(DifferentiableAttributeArgumentsSyntax(self)!)
     case .discardAssignmentExpr:
       return .discardAssignmentExpr(DiscardAssignmentExprSyntax(self)!)
+    case .discardStmt:
+      return .discardStmt(DiscardStmtSyntax(self)!)
     case .doStmt:
       return .doStmt(DoStmtSyntax(self)!)
     case .documentationAttributeArgument:
@@ -513,8 +515,6 @@ public extension Syntax {
       return .forInStmt(ForInStmtSyntax(self)!)
     case .forcedValueExpr:
       return .forcedValueExpr(ForcedValueExprSyntax(self)!)
-    case .forgetStmt:
-      return .forgetStmt(ForgetStmtSyntax(self)!)
     case .functionCallExpr:
       return .functionCallExpr(FunctionCallExprSyntax(self)!)
     case .functionDecl:

Sources/SwiftSyntax/generated/SyntaxKind.swift

@@ -102,6 +102,7 @@ public enum SyntaxKind {
   case differentiabilityParams
   case differentiableAttributeArguments
   case discardAssignmentExpr
+  case discardStmt
   case doStmt
   case documentationAttributeArgument
   case documentationAttributeArguments
@@ -126,7 +127,6 @@ public enum SyntaxKind {
   case floatLiteralExpr
   case forInStmt
   case forcedValueExpr
-  case forgetStmt
   case functionCallExpr
   case functionDecl
   case functionEffectSpecifiers
@@ -580,6 +580,8 @@ public enum SyntaxKind {
       return DifferentiableAttributeArgumentsSyntax.self
     case .discardAssignmentExpr:
       return DiscardAssignmentExprSyntax.self
+    case .discardStmt:
+      return DiscardStmtSyntax.self
     case .doStmt:
       return DoStmtSyntax.self
     case .documentationAttributeArgument:
@@ -628,8 +630,6 @@ public enum SyntaxKind {
       return ForInStmtSyntax.self
     case .forcedValueExpr:
       return ForcedValueExprSyntax.self
-    case .forgetStmt:
-      return ForgetStmtSyntax.self
     case .functionCallExpr:
       return FunctionCallExprSyntax.self
     case .functionDecl: