Merge remote-tracking branch 'upstream/main' into wasm32-wasi-test

Author: KKK669

.github/CODEOWNERS

@@ -8,7 +8,7 @@
 # Order is important. The last matching pattern has the most precedence.
 
 # Owner of anything in SwiftSyntax not owned by anyone else.
-* @ahoppen
+* @ahoppen @bnbarham
 
 # Macros
 /Sources/SwiftSyntaxMacros @DougGregor

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

@@ -105,6 +105,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
             StmtSyntax("return .choices(\(choices))")
           }
+
+          for choiceNodeName in node.elementChoices {
+            let choiceNode = SYNTAX_NODE_MAP[choiceNodeName]!
+            choiceNodeCastingMethods(for: choiceNode.kind)
+          }
         }
       }
 

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

@@ -0,0 +1,88 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SyntaxSupport
+
+@MemberBlockItemListBuilder
+func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlockItemListSyntax {
+  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.
+      public func `is`<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> Bool {
+        return self.as(syntaxType) != nil
+      }
+      """
+    )
+
+    DeclSyntax(
+      """
+      /// 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.
+      public func `as`<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> S? {
+        return S.init(self)
+      }
+      """
+    )
+
+    DeclSyntax(
+      """
+      /// Force-casts the current syntax node to the type conforming to the ``\(syntaxNodeKind.protocolType)`` protocol.
+      ///
+      /// - 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.
+      public func cast<S: \(syntaxNodeKind.protocolType)>(_ syntaxType: S.Type) -> S {
+        return self.as(S.self)!
+      }
+      """
+    )
+  } else {
+    DeclSyntax(
+      """
+      /// Checks if the current syntax node can be cast to ``\(syntaxNodeKind.syntaxType)``.
+      ///
+      /// - Returns: `true` if the node can be cast, `false` otherwise.
+      public func `is`(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> Bool {
+        return self.as(syntaxType) != nil
+      }
+      """
+    )
+
+    DeclSyntax(
+      """
+      /// Attempts to cast the current syntax node to ``\(syntaxNodeKind.syntaxType)``.
+      ///
+      /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``, or `nil` if the cast fails.
+      public func `as`(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType)? {
+        return \(syntaxNodeKind.syntaxType).init(self)
+      }
+      """
+    )
+
+    DeclSyntax(
+      """
+      /// Force-casts the current syntax node to ``\(syntaxNodeKind.syntaxType)``.
+      ///
+      /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``.
+      /// - Warning: This function will crash if the cast is not possible. Use `as` to safely attempt a cast.
+      public func cast(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType) {
+        return self.as(\(syntaxNodeKind.syntaxType).self)!
+      }
+      """
+    )
+  }
+}

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

@@ -277,5 +277,9 @@ private func generateSyntaxChildChoices(for child: Child) throws -> EnumDeclSynt
 
       StmtSyntax("return .choices(\(choices))")
     }
+
+    for choiceNode in choices {
+      choiceNodeCastingMethods(for: choiceNode.syntaxNodeKind)
+    }
   }
 }

Examples/README.md

@@ -5,6 +5,7 @@ Each example can be executed by navigating into this folder and running `swift r
 - [AddOneToIntegerLiterals](Sources/AddOneToIntegerLiterals/AddOneToIntegerLiterals.swift): Command line tool to add 1 to every integer literal in a source file
 - [CodeGenerationUsingSwiftSyntaxBuilder](Sources/CodeGenerationUsingSwiftSyntaxBuilder/CodeGenerationUsingSwiftSyntaxBuilder.swift): Code-generate a simple source file using SwiftSyntaxBuilder
 - [ExamplePlugin](Sources/ExamplePlugin): Compiler plugin executable using [`SwiftCompilerPlugin`](../Sources/SwiftCompilerPlugin)
+- [MacroExamples](Sources/MacroExamples): A collection of Swift macros
 
 Furthermore, SwiftSyntax uses [`SwiftSyntaxBuilder`](../Sources/SwiftSyntaxBuilder) extensively to generate its own code. That code can be found in the [CodeGeneration](../CodeGeneration) package.
 

Package.swift

@@ -319,12 +319,12 @@ package.targets.append(
 )
 
 if useLocalDependencies {
-  // Building standalone.
   package.dependencies += [
-    .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2")
+    .package(path: "../swift-argument-parser")
   ]
 } else {
+  // Building standalone.
   package.dependencies += [
-    .package(path: "../swift-argument-parser")
+    .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.2.2")
   ]
 }

README.md

@@ -1,106 +1,38 @@
-# SwiftSyntax
+# Swift Syntax
 
-SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.
+The swift-syntax package is a set of libraries that work on a source-accurate tree representation of Swift source code, called the SwiftSyntax tree. The SwiftSyntax tree forms the backbone of Swift’s macro system – the macro expansion nodes are represented as SwiftSyntax nodes and a macro generates a SwiftSyntax tree to be inserted into the source file.
 
 ## Documentation
 
 You can read SwiftSyntax’s documentation on [swiftpackageindex.com](https://swiftpackageindex.com/apple/swift-syntax/documentation).
 
 A great way to interactively explore the SwiftSyntax tree of a source file is https://swift-ast-explorer.com, developed by [@kishikawakatsumi](https://github.com/kishikawakatsumi).
 
-## Adding SwiftSyntax as a Dependency
+A set of example usages of swift-syntax can be found in [Examples](Examples).
 
-### Trunk Development (main)
+## Releases
 
-The mainline branch of SwiftSyntax tracks the latest developments. It is not
-an official release, and is subject to rapid changes in APIs and behaviors. To 
-use it, add this repository to the `Package.swift` manifest of your project:
+Releases of SwiftSyntax are aligned with corresponding language and tooling releases, for example the major version 509 of swift-syntax is aligned with Swift 5.9. 
+ 
+To depend on swift-syntax in a SwiftPM package, add the following to your `Package.swift`.
 
-```swift
-// swift-tools-version:5.7
-import PackageDescription
-
-let package = Package(
-  name: "MyTool",
-  dependencies: [
-    .package(url: "https://github.com/apple/swift-syntax.git", branch: "main"),
-  ],
-  targets: [
-    .target(name: "MyTool", dependencies: [
-      .product(name: "SwiftSyntax", package: "swift-syntax"),
-    ]),
-  ]
-)
-```
-
-Mainline SwiftSyntax also includes 
-
-- `SwiftParser` for natively parsing source code
-- `SwiftOperators` for folding SwiftSyntax trees containing operators
-- `SwiftSyntaxBuilder` for generating Swift code with a result builder-style interface
-- `SwiftSyntaxMacros` for providing syntactic macro support
-
-### Releases
-
-Releases of SwiftSyntax are aligned with corresponding language
-and tooling releases and are stable. To use them, 
-add this repository to the `Package.swift` manifest of your project:
 
 ```swift
-// swift-tools-version:5.7
-import PackageDescription
-
-let package = Package(
-  name: "MyTool",
-  dependencies: [
-    .package(url: "https://github.com/apple/swift-syntax.git", exact: "<#Specify Release tag#>"),
-  ],
-  targets: [
-    .target(name: "MyTool", dependencies: [
-      .product(name: "SwiftSyntax", package: "swift-syntax"),
-    ]),
-  ]
-)
+dependencies: [
+  .package(url: "https://github.com/apple/swift-syntax.git", from: "<#latest swift-syntax tag#>"),
+],
 ```
+ 
+To add swift-syntax as a dependency of your Xcode project, go to the *Package Dependencies* tab of your Xcode project, click the plus button and search for https://github.com/apple/swift-syntax.git.
 
-Replace `<#Specify Release tag#>` by the version of SwiftSyntax that you want to use (see the following table for mapping details).
-
-| Xcode Release | Swift Release Tag | SwiftSyntax Release Tag  |
-|:-------------------:|:-------------------:|:-------------------------:|
-| Xcode 14.3   | swift-5.8-RELEASE   | 508.0.0   |
-| Xcode 14.0   | swift-5.7-RELEASE   | 0.50700.1 |
-| Xcode 13.3   | swift-5.6-RELEASE   | 0.50600.1 |
-| Xcode 13.0   | swift-5.5-RELEASE   | 0.50500.0 |
-| Xcode 12.5   | swift-5.4-RELEASE   | 0.50400.0 |
-| Xcode 12.0   | swift-5.3-RELEASE   | 0.50300.0 |
-| Xcode 11.4   | swift-5.2-RELEASE   | 0.50200.0 |
-
-## Documentation
-
-SwiftSyntax uses [DocC](https://developer.apple.com/documentation/docc) bundles
-for its documentation. To view rendered documentation in Xcode, open the 
-SwiftSyntax package and select
-
-```
-Product > Build Documentation
-``` 
-
-Associated articles are written in markdown, and can be viewed in a browser, 
-text editor, or IDE.
+## Reporting Issues
 
-- [SwiftSyntax](Sources/SwiftSyntax/Documentation.docc)
-- [SwiftParser](Sources/SwiftParser/SwiftParser.docc)
-- [SwiftOperators](Sources/SwiftOperators/SwiftOperators.docc)
-- [SwiftSyntaxMacros](Sources/SwiftSyntaxMacros/SwiftSyntaxMacros.docc)
+If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).
 
 ## Contributing
 
 Start contributing to SwiftSyntax see [this guide](CONTRIBUTING.md) for more information.
 
-## Reporting Issues
-
-If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).
-
 ## Bazel
 
 SwiftSyntax provides an experimental [Bazel](https://bazel.build) build configuration, maintained by Keith Smiley. 

Release Notes/510.md

@@ -5,13 +5,16 @@
 - `SyntaxStringInterpolation.appendInterpolation(_: (some SyntaxProtocol)?)`
   - Description: Allows optional syntax nodes to be used inside string interpolation of syntax nodes. If the node is `nil`, nothing will get added to the string interpolation.
   - Pull Request: https://github.com/apple/swift-syntax/pull/2085
+  
 - `SyntaxCollection.index(at:)`
   - Description: Returns the index of the n-th element in a `SyntaxCollection`. This computation is in O(n) and `SyntaxCollection` is not subscriptable by an integer.
   - Pull Request: https://github.com/apple/swift-syntax/pull/2014
+  
 - Convenience initializer `ClosureCaptureSyntax.init()`
   - Description: Provides a convenience initializer for `ClosureCaptureSyntax` that takes a concrete `name` argument and automatically adds `equal = TokenSyntax.equalToken()` to it.
   - Issue: https://github.com/apple/swift-syntax/issues/1984
   - Pull Request: https://github.com/apple/swift-syntax/pull/2127
+  
 - Convenience initializer `EnumCaseParameterSyntax.init()`
   - Description: Provides a convenience initializer for `EnumCaseParameterSyntax` that takes a concrete `firstName` value and adds `colon = TokenSyntax.colonToken()` automatically to it.
   - Issue: https://github.com/apple/swift-syntax/issues/1984
@@ -39,6 +42,11 @@
   - Description: `is`, `as`, and `cast` methods on base node protocols with base-type conversions are marked as deprecated. The deprecated methods emit a warning that informs the developer that the cast will always succeed and should be done using the base node's initializer.
   - Issue: https://github.com/apple/swift-syntax/issues/2092
   - Pull Request: https://github.com/apple/swift-syntax/pull/2108
+  
+- Child Choice Node Casts
+  - Description: `is`, `as`, and `cast` methods for types not contained in the choice node are marked as deprecated. The deprecated methods will emit a warning, indicating that the cast will always fail.
+  - Issue: https://github.com/apple/swift-syntax/issues/2092
+  - Pull Request: https://github.com/apple/swift-syntax/pull/2184
 
 ## API-Incompatible Changes
 

Sources/SwiftParser/Declarations.swift

@@ -1040,16 +1040,25 @@ extension Parser {
   ) -> RawFunctionDeclSyntax {
     let (unexpectedBeforeFuncKeyword, funcKeyword) = self.eat(handle)
     let unexpectedBeforeIdentifier: RawUnexpectedNodesSyntax?
+    let unexpectedAfterIdentifier: RawUnexpectedNodesSyntax?
     let identifier: RawTokenSyntax
     if self.at(anyIn: Operator.self) != nil || self.at(.exclamationMark, .prefixAmpersand) {
       var name = self.currentToken.tokenText
-      if name.count > 1 && name.hasSuffix("<") && self.peek(isAt: .identifier) {
+      if !currentToken.isEditorPlaceholder && name.count > 1 && name.hasSuffix("<") && self.peek(isAt: .identifier) {
         name = SyntaxText(rebasing: name.dropLast())
       }
       unexpectedBeforeIdentifier = nil
       identifier = self.consumePrefix(name, as: .binaryOperator)
+      unexpectedAfterIdentifier = nil
     } else {
       (unexpectedBeforeIdentifier, identifier) = self.expectIdentifier(keywordRecovery: true)
+
+      if currentToken.isEditorPlaceholder {
+        let editorPlaceholder = self.parseAnyIdentifier()
+        unexpectedAfterIdentifier = RawUnexpectedNodesSyntax([editorPlaceholder], arena: self.arena)
+      } else {
+        unexpectedAfterIdentifier = nil
+      }
     }
 
     let genericParams: RawGenericParameterClauseSyntax?
@@ -1076,6 +1085,7 @@ extension Parser {
       funcKeyword: funcKeyword,
       unexpectedBeforeIdentifier,
       name: identifier,
+      unexpectedAfterIdentifier,
       genericParameterClause: genericParams,
       signature: signature,
       genericWhereClause: generics,

Sources/SwiftParser/Types.swift

@@ -936,7 +936,9 @@ extension Parser {
 
 extension Parser {
   mutating func parseResultType() -> RawTypeSyntax {
-    if self.at(prefix: "<") {
+    if self.currentToken.isEditorPlaceholder {
+      return self.parseTypeIdentifier()
+    } else if self.at(prefix: "<") {
       let generics = self.parseGenericParameters()
       let baseType = self.parseType()
       return RawTypeSyntax(

Sources/SwiftParserDiagnostics/MissingNodesError.swift

@@ -161,15 +161,27 @@ func nodesDescriptionAndCommonParent(_ nodes: [some SyntaxProtocol], format: Boo
   }
 
   let partDescriptions = NodesDescriptionPart.descriptionParts(for: missingSyntaxNodes).map({ $0.description(format: format) ?? "syntax" })
-  switch partDescriptions.count {
+
+  return (nil, formatDescriptions(partDescriptions))
+}
+
+/// Formats an array of descriptions into a single string.
+///
+/// This function takes an array of descriptions and formats them into a single string. Depending on the number
+/// of descriptions in the array, it returns different formatted strings.
+///
+/// - Parameter descriptions: An array of descriptions to be formatted.
+/// - Returns: A formatted string representing the descriptions.
+func formatDescriptions(_ descriptions: [String]) -> String {
+  switch descriptions.count {
   case 0:
-    return (nil, "syntax")
+    return "syntax"
   case 1:
-    return (nil, "\(partDescriptions.first!)")
+    return descriptions.first!
   case 2:
-    return (nil, "\(partDescriptions.first!) and \(partDescriptions.last!)")
+    return "\(descriptions.first!) and \(descriptions.last!)"
   default:
-    return (nil, "\(partDescriptions[0..<partDescriptions.count - 1].joined(separator: ", ")), and \(partDescriptions.last!)")
+    return "\(descriptions[0..<descriptions.count - 1].joined(separator: ", ")), and \(descriptions.last!)"
   }
 }