Merge pull request #2539 from bnbarham/add-introducer

Add an introducer property to DeclGroupSyntax

Author: bnbarham

CodeGeneration/Sources/SyntaxSupport/Traits.swift

@@ -47,6 +47,11 @@ public let TRAITS: [Trait] = [
  children: [
  Child(name: "attributes", kind: .node(kind: .attributeList)),
  Child(name: "modifiers", kind: .node(kind: .declModifierList)),
+ Child(
+ name: "introducer",
+ kind: .token(choices: [.keyword(.actor), .keyword(.class), .keyword(.enum), .keyword(.extension), .keyword(.protocol), .keyword(.struct)]),
+ documentation: "The token that introduces this declaration, eg. `class` for a class declaration."
+ ),
  Child(name: "inheritanceClause", kind: .node(kind: .inheritanceClause), isOptional: true),
  Child(
  name: "genericWhereClause",

Release Notes/600.md

@@ -35,7 +35,7 @@
 - `String.isValidIdentifier(for:)`
  - Description: `SwiftParser` adds an extension on `String` to check if it can be used as an identifier in a given context.
  - Pull Request: https://github.com/apple/swift-syntax/pull/2434
- 
+
 - `MacroDeclSyntax.expand`
  - the `expand(argumentList:definition:replacements:)` method gains a new parameter 'genericReplacements:' that is defaulted to an empty array.
  - The method's signature is now `expand(argumentList:definition:replacements:genericReplacements:)`
@@ -65,11 +65,16 @@
 - Type specifiers
  - Description: `AttributedTypeSyntax` can now contain multiple specifiers and these types are used to model the list of specifiers. Additionally, type specifiers can now contain arguments, like `borrow(data)`. To facilitate this, the following new types were introduces: `LifetimeSpecifierArgumentListSyntax`, `LifetimeSpecifierArgumentSyntax`, `LifetimeSpecifierArgumentsSyntax`, `LifetimeTypeSpecifierSyntax`, `SimpleTypeSpecifierSyntax`, `TypeSpecifierListSyntax`
  - Pull request: https://github.com/apple/swift-syntax/pull/2433
- 
+
+- `DeclGroupSyntax.introducer`
+ - Description: The `DeclGroupSyntax` trait has an extra `introducer` property, ie. the keyword that introduces the declaration.
+ - Issue: https://github.com/apple/sourcekit-lsp/issues/2535
+ - Pull Request: https://github.com/apple/swift-syntax/pull/2539
+
 ## API Behavior Changes
 
 ## Deprecations
- 
+
 - 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
@@ -85,7 +90,7 @@
 - `MacroExpansion{Error|Warning|FixIt}Message` moved to the `SwiftSyntaxMacros` module
  - Description: Move the `MacroExpansion{Error|Warning|FixIt}Message` types from the `SwiftSyntaxMacroExpansion` module to `SwiftSyntaxMacros`. Deprecated typealiases in `SwiftSyntaxMacroExpansion` forward to `SwiftSyntaxMacros`.
  - Pull request: https://github.com/apple/swift-syntax/pull/2338
- - Notes: The expansion diagnostic messages were defined in `SwiftSyntaxMacroExpansion`, which is intended as an implementation detail of the plugin server and should not need to be imported by macros. 
+ - Notes: The expansion diagnostic messages were defined in `SwiftSyntaxMacroExpansion`, which is intended as an implementation detail of the plugin server and should not need to be imported by macros.
 
 - `EditorPlaceholderDeclSyntax` and `EditorPlaceholderExprSyntax`:
  - Description: `EditorPlaceholderDeclSyntax` and `EditorPlaceholderExprSyntax` are now deprecated and placeholders are instead parsed as identifiers within a `MissingDeclSyntax` or `DeclReferenceExprSyntax`.
@@ -105,15 +110,15 @@
 - Effect specifiers:
  - Description: The `unexpectedAfterThrowsSpecifier` node of the various effect specifiers has been removed.
  - Pull request: https://github.com/apple/swift-syntax/pull/2219
- - Migration steps: Check `unexpectedBetweenThrowsSpecifierAndThrownError` and `unexpectedAfterThrownError` instead. 
+ - Migration steps: Check `unexpectedBetweenThrowsSpecifierAndThrownError` and `unexpectedAfterThrownError` instead.
 
 - `SyntaxKind` removed conformance to `CaseIterable`
- - Description: `SyntaxKind` no longer conforms to `CaseIterable` since there is no good use case to iterate over all syntax kinds. 
- - Pull request: https://github.com/apple/swift-syntax/pull/2292 
+ - Description: `SyntaxKind` no longer conforms to `CaseIterable` since there is no good use case to iterate over all syntax kinds.
+ - Pull request: https://github.com/apple/swift-syntax/pull/2292
  - Migration steps: Exhaustively check all the syntax nodes that your program supports. There should be no use case to iterate over all cases in `SyntaxKind`.
 
 - `IntegerLiteralExprSyntax.Radix` removed conformance to `CaseIterable`
- - Description: `IntegerLiteralExprSyntax.Radix` no longer conforms to `CaseIterable` since there is no good use case to iterate over all radix kinds. 
+ - Description: `IntegerLiteralExprSyntax.Radix` no longer conforms to `CaseIterable` since there is no good use case to iterate over all radix kinds.
  - Pull request: https://github.com/apple/swift-syntax/pull/2292
  - Migration steps: There should be no use case to iterate over all cases in `IntegerLiteralExprSyntax.Radix`.
 
@@ -127,7 +132,7 @@
  - The new classification case covers the first names of parameters in function-like declarations and the label of arguments in function-like calls.
  - Pull request: https://github.com/apple/swift-syntax/pull/2375
  - Migration steps: In exhaustive switches over `SyntaxClassification`, cover the new case.
- 
+
 - `SyntaxEnum` and `SyntaxKind` gained new cases: `throwsClause`
  - The new cases cover the newly introduced `ThrowsClauseSyntax`
  - Pull request: https://github.com/apple/swift-syntax/pull/2379
@@ -137,10 +142,10 @@
  - Description: The new property provides the lexical context in which the macro is expanded, and has several paired API changes. Types that conform to `MacroExpansionContext` will need to implement this property. Additionally, the `HostToPluginMessage` cases `expandFreestandingMacro` and `expandAttachedMacro` now include an optional `lexicalContext`. Finally, the `SyntaxProtocol.expand(macros:in:indentationWidth:)` syntactic expansion operation has been deprecated in favor of a new version `expand(macros:contextGenerator:indentationWidth:)` that takes a function produces a new macro expansion context for each expansion.
  - Pull request: https://github.com/apple/swift-syntax/pull/1554
  - Migration steps: Add the new property `lexicalContext` to any `MacroExpansionContext`-conforming types. If implementing the host-to-plugin message protocol, add support for `lexicalContext`. For macro expansion operations going through `SyntaxProtocol.expand`, provide a context generator that creates a fresh context including the lexical context.
- 
+
 - `TriviaPiece.isBackslash` in `SwiftParserDiagnostics` removed
  - Description: `TriviaPiece.isBackslash` was not intended to be public API.
- - Pull request: xxx
+ - Pull request: https://github.com/apple/swift-syntax/pull/2531
  - Migration steps: Use `if case .backslash = triviaPiece` instead
 
 ## Template

Sources/SwiftSyntax/CMakeLists.txt

@@ -14,6 +14,7 @@ add_swift_syntax_library(SwiftSyntax
  BumpPtrAllocator.swift
  CommonAncestor.swift
  Convenience.swift
+ CustomTraits.swift
  MemoryLayout.swift
  MissingNodeInitializers.swift
  SourceEdit.swift

Sources/SwiftSyntax/CustomTraits.swift

@@ -0,0 +1,82 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 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
+//
+//===----------------------------------------------------------------------===//
+
+extension ActorDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return actorKeyword
+ }
+ set {
+ actorKeyword = newValue
+ }
+ }
+}
+
+extension ClassDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return classKeyword
+ }
+ set {
+ classKeyword = newValue
+ }
+ }
+}
+
+extension EnumDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return enumKeyword
+ }
+ set {
+ enumKeyword = newValue
+ }
+ }
+}
+
+extension ExtensionDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return extensionKeyword
+ }
+ set {
+ extensionKeyword = newValue
+ }
+ }
+}
+
+extension ProtocolDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return protocolKeyword
+ }
+ set {
+ protocolKeyword = newValue
+ }
+ }
+}
+
+extension StructDeclSyntax {
+ public var introducer: TokenSyntax {
+ get {
+ return structKeyword
+ }
+ set {
+ structKeyword = newValue
+ }
+ }
+}
+
+//==========================================================================//
+// IMPORTANT: If you are tempted to add an extension here, please insert //
+// it in alphabetical order above //
+//==========================================================================//

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -72,6 +72,22 @@ public protocol DeclGroupSyntax: SyntaxProtocol, DeclSyntaxProtocol {
  set
  }
 
+ /// The token that introduces this declaration, eg. `class` for a class declaration.
+ ///
+ /// ### Tokens
+ /// 
+ /// For syntax trees generated by the parser, this is guaranteed to be one of the following kinds:
+ /// - `actor`
+ /// - `class`
+ /// - `enum`
+ /// - `extension`
+ /// - `protocol`
+ /// - `struct`
+ var introducer: TokenSyntax {
+ get
+ set
+ }
+ 
  var inheritanceClause: InheritanceClauseSyntax? {
  get
  set