Привет, Хабр! Меня зовут Сергей, я 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) }Запускаем наш тест — готово!
Итог
В статье я показал, как можно создать простой макрос, а также рассказал немного теории. Надеюсь, вы нашли что-то полезное для себя.
Расскажите в комментариях, приходилось ли вам писать макросы, и если да, то какие?
ссылка на оригинал статьи https://habr.com/ru/articles/828888/
Добавить комментарий