Привет, Хабр! Меня зовут Сергей, я iOS-разработчик в Альфа-Банке. В повседневной работе я использую множество проверенных инструментов, а в свободное время мне нравится исследовать новые возможности и расширять свои горизонты за пределами используемых в продакшене технологий.

Сегодня я хотел бы рассказать вам о макросах в Swift 5.9, как их можно применять для избавление от бойлерплейта в коде, как их создавать, какие сложности есть с ними и куда всё это движется. Так как я работаю в команде дизайн-системы, мы рассмотрим макросы на примере добавления метода copy для всех моделей UI-компонентов.

Что такое макросы в Swift

Макросы являются программами-расширениями, подключаемыми к вашему проекту и работающими во время компиляции, расширяя функциональность исходного кода до момента её компиляции.

Макросы бывают двух типов, автономные или подключаемые:

• Автономные макросы Freestanding Macrosin page link (#) — простые программы которые принимают один или больше агрументов и генерируют на их основе код. Чтобы посмотреть пример такого макроса, достаточно просто создать проект‑макрос, там будет автоносный макрос. Данные макросы хорошо подходят для создания системы логирования. Как раз #file, #fucntionc — являются представителями автономных макросов.

• Подключаемые макросы Attached Macrosin page link (@) — сложные программы которые применяются к какому‑то участку кода и добавляют к нему новую функциональность — новые методы, проперти, инициализаторы и реализация протоколов. Такие макросы дают возможность работать с AST данного куска кода. В статье мы будем подробней рассматривать именно этот тип макросов.

Создаём свой макрос

Прежде чем перейти к практической части, я добавлю немного бэкграунда про работу компонентов дизайн-системы:

• Модель компонента всегда иммутабельна (неизменяема) и является структурой

• Модель всегда лежит внутри компонента (UIView) — то есть путь для неё в общем случае будет: Component.Model

• Модель и все её проперти должны быть public

• Все проперти по возможности должны быть let, но это не всегда так, потому что некоторые проперти обёрнуты в PropertyWrapper.

• Модель обязательно должна реализовывать Equatable

Что же мы хотим получить? Нам нужен макрос, который позволит копировать иммутабельную модель с изменением параметров исходной модели. По возможности проверять, что модель собрана по общим правилам, описанным выше, и если это не так, выбрасывать ошибку с указанием, что пошло не так.

Предположим, у нас есть ProfileView, которая состоит из атрибутированного текста и статуса пользователя. Model этого компонента будет выглядеть вот так:

extension ProfileView {
  //@ViewModelCopy(ProfileView.self) - тут хотим применять наш макрос
  public struct Model: Equatable {
    // Отображаемое имя
    @Semantic // Property wrapper позволяющий сравнивать NSAttributedString 
    public private(set) var name: NSAttributedString
    // Статус аккаунта
    public let status: Status
  
    public init(
        name: NSAttributedString,
        status: Status
    ) {
        self.name = name
        self.status = status
    }  
  }
}

А как итог работы макроса мы хотим получить следующий результат:

extension ProfileView {
  public struct Model: Equatable {
    ...
  
  public func copy(build: (inout Builder) -> Void) -> Self {
      var builder = Builder(model: self)
      build(&builder)
      return .init(name: builder.name, status: builder.status)
    }

    public struct Builder {
      // Отображаемое имя
      public var name: NSAttributedString
      // Статус аккаунта
      public var status: Status
      public init(model: ProfileView.Model) {
        name = model.name
        status = model.status
      }
    }
  }
}

Начнём с создания проекта. Запускаем Xcode → File → Package, далее выбираем Swift macros и заполняем все обязательные поля.

После этого перед нами открывается проект с заранее созданным примером — stringify. Рассмотрим, что было создано:

• ViewModelCopy — это объявление нашего макроса, можно сказать, его интерфейс.

• ViewModelCopyMacro — это реализация нашего макроса.

• main — это программа‑пример, который мы можем запустить.

• ViewModelCopyTests — тесты нашего макроса.

Сгенерированный код нам не нужен, поэтому смело его удаляем и пишем нашу реализацию. Начнём с создания интерфейсной части нашего макроса — ViewModelCopy.

@attached(member, names: named(copy), named(Copy))
public macro ViewModelCopy<T>(component: T) = #externalMacro(module: "ViewModelCopyMacros", type: "ViewModelCopyMacro")

Тип нашего макроса подключаемый — @attached, подключается он как member — данный тип позволяет нам использовать макрос для создания новых структур, свойст и методов. Подробнее обо всех возможных типах можно посмотреть здесь.

Теперь самое время написать тесты на наш макрос. Переходим в файл ViewModelCopyTests. Возьмём за основу наш пример выше про ProfileView:

#if canImport(ViewModelCopyMacros)
import ViewModelCopyMacros

let testMacros: [String: Macro.Type] = [
    "ViewModelCopy": ViewModelCopyMacro.self,
]
#endif

final class ViewModelCopyTests: XCTestCase {
    func testMacro() throws {
        #if canImport(ViewModelCopyMacros)
        assertMacroExpansion(
            """
            extension ProfileView {
                @ViewModelCopy(ProfileView.self)
                public struct Model: Equatable {
                    // Отображаемое имя
                    @Semantic
                    public private(set) var name: NSAttributedString
                    // Статус аккаунта
                    public let status: Status
            
                    public init(
                        name: NSAttributedString,
                        status: Status
                    ) {
                        self.name = name
                        self.status = status
                    }
                }
            }
            """,
            expandedSource: """
            extension ProfileView {
                public struct Model: Equatable {
                    // Отображаемое имя
                    @Semantic
                    public private(set) var name: NSAttributedString
                    // Статус аккаунта
                    public let status: Status
            
                    public init(
                        name: NSAttributedString,
                        status: Status
                    ) {
                        self.name = name
                        self.status = status
                    }
            
                    public func copy(build: (inout Builder) -> Void) -> Self {
                        var builder = Builder(model: self)
                        build(&builder)
                        return .init(name: builder.name, status: builder.status)
                    }
            
                    public struct Builder {
                        // Отображаемое имя
                        public var name: NSAttributedString
                        // Статус аккаунта
                        public var status: Status
                        public init(model: ProfileView.Model) {
                            name = model.name
                            status = model.status
                        }
                    }
                }
            }
            """,
            macros: testMacros
        )
        #else
        throw XCTSkip("macros are only supported when running tests for the host platform")
        #endif
    }
}

Запускаем, тесты горят красным — значит пришло время написать реализацию ? Переходим в ViewModelCopyMacro.swift — файл, в котором будет находиться реализация нашего макроса. Удаляем всё, что есть там сейчас, и пишем нашу реализацию:

import ...

public struct ViewModelCopyMacro: MemberMacro {
    public static func expansion(of node: AttributeSyntax, providingMembersOf declaration: some DeclGroupSyntax, in context: some MacroExpansionContext) throws -> [DeclSyntax] {
        []
    }
}

@main
struct ViewModelCopyPlugin: CompilerPlugin {
    let providingMacros: [Macro.Type] = [
        ViewModelCopyMacro.self,
    ]
}

ViewModelCopyMacro — реализация нашего макроса, в ней будет находиться вся логика. ViewModelCopyPlugin — является точкой входа в наш макрос (на что намекает @main ?). Тут нужно перечислить, какие макросы объявлены в пакете, в нашем случае это только ViewModelCopyMacro.

Swift macros работает с AST, и наша задача — при разработке макроса пройтись по AST, модернизировать и вернуть измененный AST. Работать с AST — хоть и не самое сложное, но довольно монотонное занятие, так что при написании макросов нужно быть к этому готовым.

Самая большая проблема — это то, что ты не видишь сразу все AST. Но нашлись добрые люди в интернетах и написали такое замечательное web-приложение, которое как раз очень поможет нам в изучении AST. Просто вставляем из теста входное значение и получаем AST, с которым и будем работать.

Для обработки неожиданных аргументов макроса или некорректной структуры, да и в целом для любой ошибки, создадим свой набор возможных ошибок:

enum CopyError: Error, CustomStringConvertible {
    case notFoundComponentName // любая ошибка связанная с обработкой агрументов макроса
    
    var description: String {
        switch self {
        case .notFoundComponentName:
            return "Некорректный агрумент макроса. В качастве аргумента необходимо передать название компонента."
        }
    }
}

Получение имени компонента

Теперь напишем функцию, которая достаёт нам название компонента, и если не получилось достать, выбрасывает ошибку notFoundComponentName:

static func getComponentName(of node: AttributeSyntax) throws -> String {
    guard
        let arguments = node.arguments?.as(LabeledExprListSyntax.self),
        let argument = arguments.first,
        let memberAccess = argument.expression.as(MemberAccessExprSyntax.self),
        let declExpr = memberAccess.base?.as(DeclReferenceExprSyntax.self)
    else { throw CopyError.notFoundComponentName }
    return declExpr.baseName.text
}

В качестве аргумента передаём верхнеуровневый AttributedSyntax — именно в нём хранится весь AST самого макроса. Дальше мы начинаем кастить аргументы в конкретные типы. Как узнать, к чему кастить? Во-первых, можно поставить точку остановки и запустить наш тест, а во-вторых, намного удобнее воспользоваться web-приложением и посмотреть, что он нам показывает:

На вкладке Structure показывается всё AST дерево, при наведении на конкретный блок слева подсвечивается, к чему он относится. AttributedSyntax, который является аргументом нашей функции, относится к LabeledExprList, и нам нужно просто скастить к нему.

Дальше из списка аргументов достаём первый элемент (в идеале и единственный, так что можно добавить ещё проверку на количество). Дальше так же кастишь от конкретных значений к конкретным типам. Всегда можно посмотреть составляющие структуры, наведя на неё, например, как это показано для MemberAccessExprSyntax — тут можно увидеть, что дальнейшее значение лежит в свойстве base. Как итог мы получаем название параметра.

В идеале нужно ещё написать тесты. В данной статье я это опущу, и тест будет только один — который мы написали вначале.

Генерация метода copy 

Теперь перейдём к созданию метода copy. Посмотрим, из чего он состоит в нашем тесте:

public func copy(build: (inout Builder) -> Void) -> Self {
    var builder = Builder(viewModel: self)
    build(&builder)
    return Self(
        name: builder.name,
        status: builder.status
    )
}

Первые 4 строки статические, и их легко сгенерировать, а 5 и 6 строчки используют поля, перечисленные в нашей структуре. Как же нам всё это сгенерировать?

public static func expansion(of node: AttributeSyntax, providingMembersOf declaration: some DeclGroupSyntax, in context: some MacroExpansionContext) throws -> [DeclSyntax] {
    let componentName = try getComponentName(of: node)
    guard let structDecl = declaration.as(StructDeclSyntax.self) else { throw CopyError.modelIsNotStruct }
    let variables = structDecl.memberBlock.members.compactMap { member in
        return member.decl.as(VariableDeclSyntax.self)
    }
    let copyFuncDeclSyntax = createCopyFunc(with: variables)
    return []
}

static func createCopyFunc(with variables: [VariableDeclSyntax]) -> DeclSyntax {
        let identifiers = variables.compactMap { variable in
            variable.bindings.first?.as(PatternBindingSyntax.self)?.pattern.as(IdentifierPatternSyntax.self)?.identifier
        }
        var returnStr: String = ""
        identifiers.forEach { tokenSyntax in
            returnStr.append("\(tokenSyntax): builder.\(tokenSyntax),")
        }
        if !returnStr.isEmpty { returnStr.removeLast() }
        let copyFuncDeclSyntax = FunctionDeclSyntax(
            funcKeyword: .keyword(.func),
            name: "copy",
            signature: FunctionSignatureSyntax(
                parameterClause: FunctionParameterClauseSyntax(
                    leftParen: .leftParenToken(),
                    parameters: [
                        FunctionParameterSyntax(
                            firstName: "build",
                            type: FunctionTypeSyntax(
                                parameters: [
                                    TupleTypeElementSyntax(
                                        type: AttributedTypeSyntax(
                                            specifier: .keyword(.inout),
                                            attributes: [],
                                            baseType: IdentifierTypeSyntax(name: "Builder")
                                        )
                                    )
                                ],
                                returnClause: ReturnClauseSyntax(
                                    type: IdentifierTypeSyntax(name: "Void")
                                )
                            )
                        )
                    ],
                    rightParen: .rightParenToken()
                ),
                returnClause: ReturnClauseSyntax(arrow: .arrowToken(), type: IdentifierTypeSyntax(name: .keyword(.Self)))
            ),
            body: CodeBlockSyntax(
                statements: [
                    "var builder = Builder(viewModel: self)",
                    "build(&builder)",
                    "return .init(\(raw: returnStr))"
                ]
            )
        )
        return DeclSyntax(copyFuncDeclSyntax)
    }

Для начала проверим, является ли наша модель структурой. Если это не так, выбрасываем ошибку. Дальше соберём все члены модели (переменные, инициализаторы, функции и т.д.) и оставим только переменные. Swift macros позволяет нам не только смотреть, но и создавать AST как обычную структуру. В примере я демонстрирую, как это можно сделать при создании функции copy.

При создании AST дерева мы можем его полностью воссоздавать как структуру, что я делаю на примере декларации самой функции, либо можем пользоваться облегчённым строковым синтаксисом, как у меня при создании body. Мне лично нравится второй подход, так как он намного проще в чтении и последующей поддержке.

Небольшой хак: мы можем воспользоваться Swift AST Explorer, чтобы посмотреть AST для нашей функции. 

Explorer показывает нам всё дерево, которое остаётся просто повторить, а учитывая что синтаксис тут сходится, это в итоге сводится к простой монотонной работе ? 

Пишем Builder

Для нашей задачи осталось написать Builder. Ну что ж, приступим. В целом будем придерживаться примерно такого же алгоритма: смотрим на AST и пытаемся его повторить. 

static func createBuilder(_ variables: [VariableDeclSyntax], componentName: String) throws -> DeclSyntax {
        let memberBindings = variables.compactMap { $0.bindings.first }
        var params: [(name: TokenSyntax, type: TokenSyntax)] = []
        for binding in memberBindings {
            guard
                let paramName = binding.pattern.as(IdentifierPatternSyntax.self)?.identifier,
                let paramType = binding.typeAnnotation?.type.as(IdentifierTypeSyntax.self)?.name
            else { continue }
            params.append((name: paramName, type: paramType))
        }
        let builder = try StructDeclSyntax("public struct Builder") {
            for param in params {
                """
                public var \(param.name): \(param.type)
                """
            }
            try InitializerDeclSyntax("public init(model: \(raw: componentName).Model)") {
                for param in params {
                    """
                    \(param.name) = model.\(param.name)
                    """
                }
            }
        }
        return DeclSyntax(builder)
    }

Из интересного — создание StructDeclSyntax. У нас есть удобный способ создания параметров — кложура, которая возвращает MemberBlockItemListBuilder. Его в свою очередь можно просто создавать через String. Это сильно упрощает код, а главное упрощает его поддержку. Просто сравните, насколько данный способ проще, чем тот, который показан выше в создании func copy.

В конце добавляем вызов нашей функции в теле макроса и возвращаем то, что получилось:

let builderStructDeclSyntax = try createBuilder(variables, componentName: componentName)
return [copyFuncDeclSyntax, builderStructDeclSyntax]

Отлично! Наш макрос готов, осталось запустить тест и убедиться, что он работает корректно:

Оу, как мы видим, забыли добавить комментарии. Первый раз при работе с макросами я столкнулся с проблемой. Наш чудесный сайт не показывает, где хранятся комментарии и как мне их достать. Каждый MemberBlockItem показывает только блок с кодом, а комментарии опускает. Чтобы найти их, нужно перейти в вкладку Trivia, и вуаля, мы нашли наши комментарии, они лежат в leadingTrivia:

Что ж, доработаем метод createBuilder:

static func createBuilder(_ variables: [VariableDeclSyntax], componentName: String) throws -> DeclSyntax {
  let comments = variables.map { // получаем комментарии
      let comment = $0.leadingTrivia.compactMap { triviaPiece in
          switch triviaPiece {
          case let .docLineComment(comment): return comment
          default: return nil
          }
      }.first ?? ""
      return comment
  }
  let memberBindings = variables.map { $0.bindings.first }
  var params: [(name: TokenSyntax, type: TokenSyntax, comment: String)] = []
  for (index, binding) in memberBindings.enumerated() {
      guard
          let paramName = binding?.pattern.as(IdentifierPatternSyntax.self)?.identifier,
          let paramType = binding?.typeAnnotation?.type.as(IdentifierTypeSyntax.self)?.name
      else { continue }
      params.append((name: paramName, type: paramType, comment: comments[index]))
  }
  let builder = try StructDeclSyntax("public struct Builder") {
      for param in params {
          """
          \(raw: param.comment)
          public var \(param.name): \(param.type)
          """
      }
      try InitializerDeclSyntax("public init(model: \(raw: componentName).Model)") {
          for param in params {
              """
              \(param.name) = model.\(param.name)
              """
          }
      }
  }
  return DeclSyntax(builder)
}

Запускаем наш тест — готово!

Итог

В статье я показал, как можно создать простой макрос, а также рассказал немного теории. Надеюсь, вы нашли что-то полезное для себя.

Расскажите в комментариях, приходилось ли вам писать макросы, и если да, то какие?