Swift 宏：深入探索獨立宏的潛力

摘要

本文章深入探討 Swift 宏及其在現代開發中的重要性，揭示了這項技術如何改變我們編寫程式碼的方式。 歸納要點:

• Swift 宏的演進從早期概念到獨立宏的成熟應用,展現了其設計理念與實現方式的變化。
• SwiftSyntax 在獨立宏開發中扮演關鍵角色,提供解析程式碼結構及操作語法樹的工具和技巧。
• 獨立宏在程式碼生成、驗證、最佳化等場景中的實務應用,不僅提升程式碼品質,也增強開發效率。

Swift Macros：革新程式碼開發的強大工具

SwiftSyntax 與獨立宏：提升程式碼品質與可維護性的利器

// swift-tools-version: 5.10 // The swift-tools-version declares the minimum version of Swift required to build this package.  import PackageDescription import CompilerPluginSupport  let package = Package(     name: "Stringfy",     platforms: [.macOS(.v10_15), .iOS(.v13), .tvOS(.v13), .watchOS(.v6), .macCatalyst(.v13)],     products: [         // Products define the executables and libraries a package produces, making them visible to other packages.         .library(             name: "Stringfy",             targets: ["Stringfy"]         ),         .executable(             name: "StringfyClient",             targets: ["StringfyClient"]         ),     ],     dependencies: [         .package(url: "https://github.com/apple/swift-syntax.git", from: "509.0.0"),     ],     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: "StringfyMacros",             dependencies: [                 .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: "Stringfy", dependencies: ["StringfyMacros"]),          // A client of the library, which is able to use the macro in its own code.         .executableTarget(name: "StringfyClient", dependencies: ["Stringfy"]),          // A test target used to develop the macro implementation.         .testTarget(             name: "StringfyTests",             dependencies: [                 "StringfyMacros",                 .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),             ]         ),     ] )

/// 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(_ value: T) -> (T, String) = #externalMacro(module: "StringfyMacros", type: "StringifyMacro")

/// 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 {         guard let argument = node.argumentList.first?.expression else {             fatalError("compiler bug: the macro does not have any arguments")         }          return "(\(argument), \(literal: argument.description))"     } }  @main struct StringfyPlugin: CompilerPlugin {     let providingMacros: [Macro.Type] = [         StringifyMacro.self,     ] }

import Stringfy  let a = 17 let b = 25  let (result, code) = #stringify(a + b)  print("The value \(result) was produced by the code \"\(code)\"")

import Foundation  /// The `URL` macro is a Swift macro designed to facilitate the creation of `URL` objects from string literals. /// This macro ensures that the provided string is a valid URL at compile time, reducing runtime errors /// related to invalid URLs. /// /// - Parameters: ///   - string: A `String` representing the URL. This string is validated at compile time to ensure it ///   is well-formed and can be safely used as a `URL`. /// /// - Returns: ///   A `URL` object initialized with the provided string. /// /// - Example: /// ///     ```swift ///     let website = #URL("https://sisal.com.tr") /// ///     // If the string is not a valid URL, the compiler will raise an error. If it is valid, it will return ///     // a non-optional `URL` object. ///     ```  @freestanding(expression) public macro URL(_ string: StaticString) -> URL = #externalMacro(module: "SisalMacros", type: "URLMacro")

import Foundation  public struct URLMacro: ExpressionMacro {          static let invalidCharacters = CharacterSet.urlQueryAllowed         .union(CharacterSet(charactersIn: "%+?#[]"))         .inverted          static let urlSchemeAllowedCharacters = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: ".-"))          public static func expansion(of node: some SwiftSyntax.FreestandingMacroExpansionSyntax, in context: some SwiftSyntaxMacros.MacroExpansionContext) throws -> SwiftSyntax.ExprSyntax {                  guard node.argumentList.count == 1 else {             throw MacroError.message("#URL should have one String literal argument")         }                  guard let literal = node.argumentList.first?.expression.as(StringLiteralExprSyntax.self),               literal.segments.count == 1,               let string = literal.segments.first?.as(StringSegmentSyntax.self)?.content else {             throw MacroError.message("#URL should be a String literal")         }                  if let idx = string.text.rangeOfCharacter(from: Self.invalidCharacters)?.lowerBound {             throw MacroError.message("\"\(string.text)\" has invalid character at index \(string.text.distance(from: string.text.startIndex, to: idx)) (\(string.text[idx]))")         }                  guard let scheme = string.text.range(of: ":").map({ string.text[..<$0.lowerBound] }),               scheme.rangeOfCharacter(from: Self.urlSchemeAllowedCharacters.inverted) == nil else {             throw MacroError.message("URL must contain a scheme")         }                  guard let url = URL(string: string.text) else {             throw MacroError.message("\"\(string.text)\" is not a valid URL")         }                  guard url.scheme == String(scheme) else {             throw MacroError.message("URL must contain a scheme")         }                  guard url.absoluteString == string.text else {             throw MacroError.message("Resulting URL \"\(url.absoluteString)\" is not equal to \"\(string.text)\"")         }                  return "URL(string: \"\(raw: string.text)\")!"     } }  enum MacroError: Error, CustomStringConvertible {          case message(String)          var description: String {         switch self {         case .message(let text):             return text         }     } }

@main struct SisalPlugin: CompilerPlugin {     let providingMacros: [Macro.Type] = [         URLMacro.self     ] }

import Sisal import Foundation // WARNING: Don't forget to add Foundation to see results for this example.  // A function to send a GET request to an API func fetchData(from url: URL) {     let task = URLSession.shared.dataTask(with: url) { data, response, error in         if let error = error {             print("An error occurred: \(error)")             return         }                  guard let data = data else {             print("No data received.")             return         }                  // Process the received data (e.g., JSON parsing)         if let jsonString = String(data: data, encoding: .utf8) {             print("Received data: \(jsonString)")         }     }     task.resume() }  // Valid URL using the #URL macro let validAPIEndpoint = #URL("https://api.sisal.com.tr/v1/data")  // Invalid URLs to demonstrate error handling by our URL macro // let missingScheme = #URL("api.sisal.com.tr/v1/data") // Error: URL must contain a scheme // let invalidCharacter = #URL("https://api.sisal.com.tr/v1/data?query=hello world!") // Error: "https://api.sisal.com.tr/v1/data?query=hello world!" has invalid character at index 44 ( ) // let multipleArguments = #URL("https://sisal.com.tr", "https://example.com") // Error: Extra argument in macro expansion // let invalidURLFormat = #URL("https://:invalid-url") // Error: "https://:invalid-url" is not a valid URL  // Start fetching data from the valid API endpoint fetchData(from: validAPIEndpoint)

/// The `@Unique` macro is a custom Swift macro designed to automatically generate /// a unique function name within a class. This can be useful in scenarios where /// you need to avoid name collisions or want to ensure that a function has a distinct name /// within a class. /// /// The macro is declared as a freestanding declaration macro and can be applied to any class /// to inject a function with a unique name. /// /// - Example: /// /// ```swift /// @Unique /// public class MyClass { ///     // The class will have a uniquely named function automatically generated ///     // by the macro. The function name is guaranteed to be unique within the scope of the class. /// } /// ```  @freestanding(declaration, names: named(MyClass)) public macro Unique() = #externalMacro(module: "SisalMacros", type: "UniqueMacro")

/// The `UniqueMacro` is the implementation of the `@Unique` macro. It conforms to the `DeclarationMacro` /// protocol, which defines the behavior of macros that generate declarations, such as classes, /// functions, or variables. /// /// This macro generates a unique function name by appending a unique identifier to the function name. /// The generated function is inserted into the class where the macro is applied.  public enum UniqueMacro: DeclarationMacro {          /// Expands the `@Unique` macro into a class declaration with a uniquely named function.     ///     /// - Parameters:     ///   - node: The syntax node where the macro is applied. This represents the location in the source code     ///   where the macro is invoked.     ///   - context: The context in which the macro is expanded. This provides additional information and tools     ///   needed to generate the code, such as generating unique names.     ///     /// - Returns: An array of `DeclSyntax` representing the generated declarations. In this case, it returns     ///   a class declaration with a uniquely named function.     ///     /// - Throws: If the macro encounters an error during expansion, it throws an error that will be reported     ///   to the developer.      public static func expansion(         of node: some FreestandingMacroExpansionSyntax,         in context: some MacroExpansionContext     ) throws -> [DeclSyntax] {                  let name = context.makeUniqueName("unique")            return [       """       class MyClass {         func \(name)() {}       }       """         ]     } }

@main struct SisalPlugin: CompilerPlugin {     let providingMacros: [Macro.Type] = [         UniqueMacro.self     ] }

獨立宏：提升 Swift 程式碼品質與效率的利器