create freestanding macro

Author: leogdion

Macros/SKSampleMacro/.gitignore

@@ -0,0 +1,8 @@
+.DS_Store
+/.build
+/Packages
+xcuserdata/
+DerivedData/
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+.netrc

Macros/SKSampleMacro/Package.resolved

@@ -0,0 +1,59 @@
+// swift-tools-version: 6.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+import CompilerPluginSupport
+
+let package = Package(
+    name: "SKSampleMacro",
+    platforms: [
+      .macOS(.v13),
+      .iOS(.v13),
+      .watchOS(.v6),
+      .tvOS(.v13),
+      .visionOS(.v1)
+    ],
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "SKSampleMacro",
+            targets: ["SKSampleMacro"]
+        ),
+        .executable(
+            name: "SKSampleMacroClient",
+            targets: ["SKSampleMacroClient"]
+        ),
+    ],
+    dependencies: [
+      .package(path: "../.."),
+      .package(url: "https://github.com/apple/swift-syntax.git", from: "601.0.1")
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        // Macro implementation that performs the source transformation of a macro.
+        .macro(
+            name: "SKSampleMacroMacros",
+            dependencies: [
+                .product(name: "SyntaxKit", package: "SyntaxKit"),
+                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
+                .product(name: "SwiftCompilerPlugin", package: "swift-syntax")
+            ]
+        ),
+
+        // Library that exposes a macro as part of its API, which is used in client programs.
+        .target(name: "SKSampleMacro", dependencies: ["SKSampleMacroMacros"]),
+
+        // A client of the library, which is able to use the macro in its own code.
+        .executableTarget(name: "SKSampleMacroClient", dependencies: ["SKSampleMacro"]),
+
+        // A test target used to develop the macro implementation.
+        .testTarget(
+            name: "SKSampleMacroTests",
+            dependencies: [
+                "SKSampleMacroMacros",
+                .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
+            ]
+        ),
+    ]
+)

Macros/SKSampleMacro/Package.swift

@@ -0,0 +1,11 @@
+// The Swift Programming Language
+// https://docs.swift.org/swift-book
+
+/// A macro that produces both a value and a string containing the
+/// source code that generated the value. For example,
+///
+///     #stringify(x + y)
+///
+/// produces a tuple `(x + y, "x + y")`.
+@freestanding(expression)
+public macro stringify<T>(_ lhs: T, _ rhs: T) -> (T, String) = #externalMacro(module: "SKSampleMacroMacros", type: "StringifyMacro")

Macros/SKSampleMacro/Sources/SKSampleMacro/SKSampleMacro.swift

@@ -0,0 +1,8 @@
+import SKSampleMacro
+
+let a = 17
+let b = 25
+
+let (result, code) = #stringify(a, b)
+
+print("The value \(result) was produced by the code \"\(code)\"")

Macros/SKSampleMacro/Sources/SKSampleMacroClient/main.swift

@@ -0,0 +1,42 @@
+import SwiftCompilerPlugin
+import SwiftSyntax
+//import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+import SyntaxKit
+
+/// Implementation of the `stringify` macro, which takes an expression
+/// of any type and produces a tuple containing the value of that expression
+/// and the source code that produced the value. For example
+///
+///     #stringify(x + y)
+///
+///  will expand to
+///
+///     (x + y, "x + y")
+public struct StringifyMacro: ExpressionMacro {
+    public static func expansion(
+        of node: some FreestandingMacroExpansionSyntax,
+        in context: some MacroExpansionContext
+    ) -> ExprSyntax {
+      let first = node.arguments.first?.expression
+      let second = node.arguments.last?.expression
+      guard let first, let second  else {
+          fatalError("compiler bug: the macro does not have any arguments")
+      }
+      
+      return Tuple{
+        Infix("+") {
+          VariableExp(first.description)
+          VariableExp(second.description)
+        }
+        Literal.string("\(first.description) + \(second.description)")
+      }.expr
+    }
+}
+
+@main
+struct SKSampleMacroPlugin: CompilerPlugin {
+    let providingMacros: [Macro.Type] = [
+        StringifyMacro.self,
+    ]
+}

Macros/SKSampleMacro/Sources/SKSampleMacroMacros/SKSampleMacroMacro.swift

@@ -0,0 +1,48 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+import SwiftSyntaxMacrosTestSupport
+import XCTest
+
+// Macro implementations build for the host, so the corresponding module is not available when cross-compiling. Cross-compiled tests may still make use of the macro itself in end-to-end tests.
+#if canImport(SKSampleMacroMacros)
+import SKSampleMacroMacros
+
+let testMacros: [String: Macro.Type] = [
+    "stringify": StringifyMacro.self,
+]
+#endif
+
+final class SKSampleMacroTests: XCTestCase {
+    func testMacro() throws {
+        #if canImport(SKSampleMacroMacros)
+        assertMacroExpansion(
+            """
+            #stringify(a + b)
+            """,
+            expandedSource: """
+            (a + b, "a + b")
+            """,
+            macros: testMacros
+        )
+        #else
+        throw XCTSkip("macros are only supported when running tests for the host platform")
+        #endif
+    }
+
+    func testMacroWithStringLiteral() throws {
+        #if canImport(SKSampleMacroMacros)
+        assertMacroExpansion(
+            #"""
+            #stringify("Hello, \(name)")
+            """#,
+            expandedSource: #"""
+            ("Hello, \(name)", #""Hello, \(name)""#)
+            """#,
+            macros: testMacros
+        )
+        #else
+        throw XCTSkip("macros are only supported when running tests for the host platform")
+        #endif
+    }
+}

Macros/SKSampleMacro/Tests/SKSampleMacroTests/SKSampleMacroTests.swift

@@ -0,0 +1,30 @@
+//
+//  CodeBlock+ExprSyntax.swift
+//  SyntaxKit
+//
+//  Created by Leo Dion.
+//  Provides convenience for converting a CodeBlock into ExprSyntax when appropriate.
+//
+
+import SwiftSyntax
+
+extension CodeBlock {
+  /// Attempts to treat this `CodeBlock` as an expression and return its `ExprSyntax` form.
+  ///
+  /// If the underlying syntax already *is* an `ExprSyntax`, it is returned directly. If the
+  /// underlying syntax is a bare `TokenSyntax` (commonly the case for `VariableExp` which
+  /// produces an identifier token), we wrap it in a `DeclReferenceExprSyntax` so that it becomes
+  /// a valid expression node. Any other kind of syntax results in a runtime error, because it
+  /// cannot be represented as an expression (e.g. declarations or statements).
+  public var expr: ExprSyntax {
+    if let expr = self.syntax.as(ExprSyntax.self) {
+      return expr
+    }
+
+    if let token = self.syntax.as(TokenSyntax.self) {
+      return ExprSyntax(DeclReferenceExprSyntax(baseName: .identifier(token.text)))
+    }
+
+    fatalError("CodeBlock of type \(type(of: self.syntax)) cannot be represented as ExprSyntax")
+  }
+} 

Package.resolved

@@ -0,0 +1,70 @@
+//
+//  Infix.swift
+//  SyntaxKit
+//
+//  Created by Leo Dion.
+//  Copyright © 2025 BrightDigit.
+//
+//  Permission is hereby granted, free of charge, to any person
+//  obtaining a copy of this software and associated documentation
+//  files (the “Software”), to deal in the Software without
+//  restriction, including without limitation the rights to use,
+//  copy, modify, merge, publish, distribute, sublicense, and/or
+//  sell copies of the Software, and to permit persons to whom the
+//  Software is furnished to do so, subject to the following
+//  conditions:
+//
+//  The above copyright notice and this permission notice shall be
+//  included in all copies or substantial portions of the Software.
+//
+//  THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+//  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+//  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+//  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+//  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+//  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+//  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+//  OTHER DEALINGS IN THE SOFTWARE.
+//
+
+import SwiftSyntax
+
+/// A generic binary (infix) operator expression, e.g. `a + b`.
+public struct Infix: CodeBlock {
+  private let op: String
+  private let operands: [CodeBlock]
+
+  /// Creates an infix operator expression.
+  /// - Parameters:
+  ///   - op: The operator symbol as it should appear in source (e.g. "+", "-", "&&").
+  ///   - content: A ``CodeBlockBuilder`` that supplies the two operand expressions.
+  ///
+  /// Exactly two operands must be supplied – a left-hand side and a right-hand side.
+  public init(_ op: String, @CodeBlockBuilderResult _ content: () -> [CodeBlock]) {
+    self.op = op
+    self.operands = content()
+  }
+
+  public var syntax: SyntaxProtocol {
+    guard operands.count == 2 else {
+      fatalError("Infix expects exactly two operands, got \(operands.count).")
+    }
+
+    let left = operands[0].expr
+    let right = operands[1].expr
+
+    let operatorExpr = ExprSyntax(
+      BinaryOperatorExprSyntax(
+        operator: .binaryOperator(op, leadingTrivia: .space, trailingTrivia: .space)
+      )
+    )
+
+    return SequenceExprSyntax(
+      elements: ExprListSyntax([
+        left,
+        operatorExpr,
+        right,
+      ])
+    )
+  }
+}