[Macros] Introduce (Freestanding)DeclarationMacro and implement expansion

Freestanding declaration macros are spelled in the same manner as
expression macros, with a leading `#`. Introduce a protocol with their
expansion operation and implement expansion semantics in the macro
system for testing purposes.

Author: DougGregor

Sources/_SwiftSyntaxMacros/CMakeLists.txt

@@ -7,7 +7,9 @@
 # See http://swift.org/CONTRIBUTORS.txt for Swift project authors
 
 add_swift_host_library(_SwiftSyntaxMacros
+  DeclarationMacro.swift
   ExpressionMacro.swift
+  FreestandingDeclarationMacro.swift
   Macro.swift
   MacroExpansionContext.swift
   MacroSystem.swift

Sources/_SwiftSyntaxMacros/DeclarationMacro.swift

@@ -0,0 +1,16 @@
+//
+// 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 SwiftParser
+import SwiftDiagnostics
+
+/// Describes a macro that forms declarations.
+public protocol DeclarationMacro: Macro {
+}

Sources/_SwiftSyntaxMacros/FreestandingDeclarationMacro.swift

@@ -0,0 +1,21 @@
+//
+// 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 SwiftParser
+import SwiftDiagnostics
+
+/// Describes a macro that forms declarations.
+public protocol FreestandingDeclarationMacro: DeclarationMacro {
+  /// Expand a macro described by the given freestanding macro expansion
+  /// declaration within the given context to produce a set of declarations.
+  static func expansion(
+    of node: MacroExpansionDeclSyntax, in context: inout MacroExpansionContext
+  ) throws -> [DeclSyntax]
+}

Sources/_SwiftSyntaxMacros/MacroSystem.swift

@@ -86,18 +86,75 @@ class MacroApplication: SyntaxRewriter {
   override func visit(_ node: CodeBlockItemListSyntax) -> CodeBlockItemListSyntax {
     var newItems: [CodeBlockItemSyntax] = []
     for item in node {
+      // Expand declaration macros that were parsed as macro expansion
+      // expressions in this context.
+      if case let .expr(exprItem) = item.item,
+         let exprExpansion = exprItem.as(MacroExpansionExprSyntax.self),
+         let macro = macroSystem.macros[exprExpansion.macro.text],
+         let freestandingMacro = macro as? FreestandingDeclarationMacro.Type {
+        do {
+          let expandedDecls = try freestandingMacro.expansion(
+            of: exprExpansion.asMacroExpansionDecl(), in: &context
+          )
+
+          newItems.append(contentsOf: expandedDecls.map { decl in
+            CodeBlockItemSyntax(item: .decl(decl))
+          })
+        } catch {
+          // Record the error
+          context.diagnose(
+            Diagnostic(
+              node: Syntax(node),
+              message: ThrownErrorDiagnostic(message: String(describing: error))
+            )
+          )
+        }
+
+        continue
+      }
+
       // Recurse on the child node.
       let newItem = visit(item.item)
+      newItems.append(item.withItem(newItem))
+    }
+
+    return CodeBlockItemListSyntax(newItems)
+  }
 
-      // Flatten if we get code block item list syntax back.
-      if let itemList = newItem.as(CodeBlockItemListSyntax.self) {
-        newItems.append(contentsOf: itemList)
-      } else {
-        newItems.append(item.withItem(newItem))
+  override func visit(_ node: MemberDeclListSyntax) -> MemberDeclListSyntax {
+    var newItems: [MemberDeclListItemSyntax] = []
+    for item in node {
+        // Expand declaration macros, which produce zero or more declarations.
+      if let declExpansion = item.decl.as(MacroExpansionDeclSyntax.self),
+         let macro = macroSystem.macros[declExpansion.macro.text],
+         let freestandingMacro = macro as? FreestandingDeclarationMacro.Type {
+        do {
+          let expandedDecls = try freestandingMacro.expansion(
+            of: declExpansion, in: &context
+          )
+
+          newItems.append(contentsOf: expandedDecls.map { decl in
+            MemberDeclListItemSyntax(decl: decl)
+          })
+        } catch {
+            // Record the error
+          context.diagnose(
+            Diagnostic(
+              node: Syntax(node),
+              message: ThrownErrorDiagnostic(message: String(describing: error))
+            )
+          )
+        }
+
+        continue
       }
+
+      // Recurse on the child node.
+      let newDecl = visit(item.decl)
+      newItems.append(item.withDecl(newDecl))
     }
 
-    return CodeBlockItemListSyntax(newItems)
+    return .init(newItems)
   }
 }
 

Sources/_SwiftSyntaxMacros/Syntax+MacroEvaluation.swift

@@ -25,6 +25,29 @@ struct ThrownErrorDiagnostic: DiagnosticMessage {
 }
 
 extension MacroExpansionExprSyntax {
+  /// Macro expansion declarations are parsed in some positions where an
+  /// expression is also warranted, so
+  func asMacroExpansionDecl() -> MacroExpansionDeclSyntax {
+    MacroExpansionDeclSyntax(
+      unexpectedBeforePoundToken,
+      poundToken: poundToken,
+      unexpectedBetweenPoundTokenAndMacro,
+      macro: macro,
+      genericArguments: genericArguments,
+      unexpectedBetweenGenericArgumentsAndLeftParen,
+      leftParen: leftParen,
+      unexpectedBetweenLeftParenAndArgumentList,
+      argumentList: argumentList,
+      unexpectedBetweenArgumentListAndRightParen,
+      rightParen: rightParen,
+      unexpectedBetweenRightParenAndTrailingClosure,
+      trailingClosure: trailingClosure,
+      unexpectedBetweenTrailingClosureAndAdditionalTrailingClosures,
+      additionalTrailingClosures: additionalTrailingClosures,
+      unexpectedAfterAdditionalTrailingClosures
+    )
+  }
+
   /// Evaluate the given macro for this syntax node, producing the expanded
   /// result and (possibly) some diagnostics.
   func evaluateMacro(
@@ -53,29 +76,6 @@ extension MacroExpansionExprSyntax {
 }
 
 extension MacroExpansionDeclSyntax {
-  /// Macro expansion declarations are parsed in some positions where an
-  /// expression is also warranted, so
-  private func asMacroExpansionExpr() -> MacroExpansionExprSyntax {
-    MacroExpansionExprSyntax(
-      unexpectedBeforePoundToken,
-      poundToken: poundToken,
-      unexpectedBetweenPoundTokenAndMacro,
-      macro: macro,
-      genericArguments: genericArguments,
-      unexpectedBetweenGenericArgumentsAndLeftParen,
-      leftParen: leftParen,
-      unexpectedBetweenLeftParenAndArgumentList,
-      argumentList: argumentList,
-      unexpectedBetweenArgumentListAndRightParen,
-      rightParen: rightParen,
-      unexpectedBetweenRightParenAndTrailingClosure,
-      trailingClosure: trailingClosure,
-      unexpectedBetweenTrailingClosureAndAdditionalTrailingClosures,
-      additionalTrailingClosures: additionalTrailingClosures,
-      unexpectedAfterAdditionalTrailingClosures
-    )
-  }
-
   /// Evaluate the given macro for this syntax node, producing the expanded
   /// result and (possibly) some diagnostics.
   func evaluateMacro(
@@ -84,10 +84,7 @@ extension MacroExpansionDeclSyntax {
   ) -> Syntax {
     // TODO: declaration/statement macros
 
-    // Fall back to evaluating as an expression macro.
-    return Syntax(
-      asMacroExpansionExpr().evaluateMacro(macro, in: &context)
-    )
+    return Syntax(self)
   }
 }
 

Tests/SwiftSyntaxMacrosTest/MacroSystemTests.swift

@@ -154,12 +154,12 @@ extension SimpleDiagnosticMessage: FixItMessage {
   var fixItID: MessageID { diagnosticID }
 }
 
-public struct ErrorMacro: ExpressionMacro {
+public struct ErrorMacro: FreestandingDeclarationMacro {
   public static func expansion(
-    of macro: MacroExpansionExprSyntax,
+    of node: MacroExpansionDeclSyntax,
     in context: inout MacroExpansionContext
-  ) throws -> ExprSyntax {
-    guard let firstElement = macro.argumentList.first,
+  ) throws -> [DeclSyntax] {
+    guard let firstElement = node.argumentList.first,
       let stringLiteral = firstElement.expression
         .as(StringLiteralExprSyntax.self),
       stringLiteral.segments.count == 1,
@@ -170,7 +170,7 @@ public struct ErrorMacro: ExpressionMacro {
 
     context.diagnose(
       Diagnostic(
-        node: Syntax(macro),
+        node: Syntax(node),
         message: SimpleDiagnosticMessage(
           message: messageString.content.description,
           diagnosticID: MessageID(domain: "test", id: "error"),
@@ -179,7 +179,31 @@ public struct ErrorMacro: ExpressionMacro {
       )
     )
 
-    return "()"
+    return []
+  }
+}
+
+struct DefineBitwidthNumberedStructsMacro: FreestandingDeclarationMacro {
+  static func expansion(
+    of node: MacroExpansionDeclSyntax,
+    in context: inout MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    guard let firstElement = node.argumentList.first,
+      let stringLiteral = firstElement.expression
+        .as(StringLiteralExprSyntax.self),
+      stringLiteral.segments.count == 1,
+      case let .stringSegment(prefix) = stringLiteral.segments[0]
+    else {
+      throw CustomError.message(
+        "#bitwidthNumberedStructs macro requires a string literal")
+    }
+
+    return [8, 16, 32, 64].map { bitwidth in
+      """
+
+      struct \(raw: prefix)\(raw: String(bitwidth)) { }
+      """
+    }
   }
 }
 
@@ -243,6 +267,7 @@ public let testMacros: [String: Macro.Type] = [
   "imageLiteral": ImageLiteralMacro.self,
   "stringify": StringifyMacro.self,
   "myError": ErrorMacro.self,
+  "bitwidthNumberedStructs": DefineBitwidthNumberedStructsMacro.self,
 ]
 
 final class MacroSystemTests: XCTestCase {
@@ -320,18 +345,44 @@ final class MacroSystemTests: XCTestCase {
     AssertMacroExpansion(
       macros: testMacros,
       """
-      _ = #myError("please don't do that")
-      _ = #myError(bad)
+      #myError("please don't do that")
+      struct X {
+        func f() { }
+        #myError(bad)
+        func g() {
+          #myError("worse")
+        }
+      }
       """,
       """
-      _ = ()
-      _ = #myError(bad)
+
+      struct X {
+        func f() { }
+        func g() {
+        }
+      }
       """,
       diagnosticStrings: [
         "please don't do that",
         "#error macro requires a string literal",
+        "worse",
       ]
     )
   }
 
+  func testBitwidthNumberedStructsExpansion() {
+    AssertMacroExpansion(
+      macros: testMacros,
+      """
+      #bitwidthNumberedStructs("MyInt")
+      """,
+      """
+
+      struct MyInt8 { }
+      struct MyInt16 { }
+      struct MyInt32 { }
+      struct MyInt64 { }
+      """
+    )
+  }
 }