DEV Community: Francesco Leoni

How to Create Swift Macros with Xcode 15

Francesco Leoni — Wed, 21 Jun 2023 06:36:53 +0000

Here you can find this articles and many more about iOS and macOS Development.

What are Macros?

Swift Macros allow you to generate repetitive code at compile time, making your app's codebase more easier to read and less tedious to write.

There are two types of macros:

Freestanding macros stand in place of something else in your code. They always start with a hashtag (#) sign.

#caseDetection // Freestanding Macro

Attached macros are used as attributes on declarations in your code. They start with an @ sign.

@CaseDetection // Attached Macro

Create new Macro

Macros need to be created in a special Package that depends on swift-syntax library.

SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code. Here is the GitHub repo.

To create a new Macro go to New -> Package and select Swift Macro.
Type the name of your Macro and create the Package.

Type only the actual name of the macro, without Macro suffix. Eg. for a Macro named AddAsync, type AddAsync not AddAsyncMacro.

Macro Package structure

Inside the newly created Package you will find some auto-generated files:

[Macro name].swift where you declare the signature of your Macro
main.swift where you can test the behaviour of the Macro
[Macro name]Macro.swift where you write the actual implementation of the Macro
[Macro name]Tests.swift where you write the tests of the Macro implementation

Macro roles

A single Macro can have multiple roles that will define its behaviour.
The available roles are:

@freestanding(expression)

Creates a piece of code that returns a value.

Protocol

ExpressionMacro

Declaration

@freestanding(expression)

@freestanding(declaration)

Creates one or more declarations. Like struct, function, variable or type.

Protocol

DeclarationMacro

Declaration

@freestanding (declaration, names: arbitrary)

@attached(peer)

Adds new declarations alongside the declaration it's applied to.

Protocol

PeerMacro

Declaration

@attached(peer, names: overloaded)

@attached(accessor)

Adds accessors to a property. Eg. adds get and set to a var. For example the @State in SwiftUI.

Protocol

AccessorMacro

Declaration

@attached(accessor)

@attached (memberAttribute)

Adds attributes to the declarations in the type/extension it's applied to.

Protocol

MamberAttributeMacro

Declaration

@attached(memberAttribute)

@attached (member)

Adds new declarations inside the type/extension it's applied to. Eg. adds a custom init() inside a struct.

Protocol

MemberMacro

Declaration

@attached(member, names: named(init()))

@attached(conformance)

Adds conformances to protocols.

Protocol

ConformanceMacro

Declaration

@attached(conformance)

Build Macro

Signature

In this guide we will create a Macro that creates an async function off of a completion one.
To start building this Macro we need to create the Macro signature.
To do this, go to [Macro name].swift file and add.

@attached(peer, names: overloaded)
public macro AddAsync() = #externalMacro(module: "AddAsyncMacros", type: "AddAsyncMacro")

Here you declare the name of the Macro (AddAsync), then in the #externalMacro you specify the module it is in and the type of the Macro.

Implementation

Then to implement the actual Macro, go to the [Macro name]Macro.swift file.
Create a public struct named accordingly with the name of the Macro and add conformance to protocols based on the signature you specified in the Macro signature.
So, inside newly created struct and add the required method.

public struct AddAsyncMacro: PeerMacro {

   public static func expansion(of node: AttributeSyntax, providingPeersOf declaration: some DeclSyntaxProtocol, in context: some MacroExpansionContext) throws -> [DeclSyntax] {
      // Implement macro
   }
}

If your Macro signature has more than one role you need to add conformance to each role, for example:

// Signature
@attached(accessor)
@attached(memberAttribute)
@attached(member, names: named(init()))
public macro // ...

// Implementation
public struct MyMacro: AccessorMacro, MamberAttributeMacro, MemberMacro { }

To know the corresponding protocols see Macro roles section.

Exporting the Macro

Inside [Macro name]Macro.swift file add or edit this piece of code with to newly created Macro.

@main
struct AddAsyncMacroPlugin: CompilerPlugin {
  let providingMacros: [SwiftSyntaxMacros.Macro.Type] = [
    AddAsyncMacro.self
  ]
}

Expansion method

The expansion method is responsible for generating the hidden code.
Here the piece of code the Macro (declaration) is attached on, is broken into pieces (TokenSyntax) and manipulated to generate the desired additional code.

To do this we have to cast the declaration to the desired syntax.
Eg. If the Macro can be attached to a struct we will cast it to StructDeclSyntax.
In this case the Macro can only be attached to a function so we will cast it to FunctionDeclSyntax.
So, inside the expansion method add:

guard let functionDecl = declaration.as(FunctionDeclSyntax.self) else {
   // TODO: Throw error
}

return []

Now, before we continue, we need to write a test that checks whether the implementation of the Macro generates the code we expect.
So, in [Macro name]Tests.swift file add:

func test_AddAsync() {
    assertMacroExpansion(
        """
        @AddAsync
        func test(arg1: String, completion: (String?) -> Void) {

        }
        """,
        expandedSource: """

        func test(arg1: String, completion: (String?) -> Void) {

        }

        func test(arg1: String) async -> String? {
          await withCheckedContinuation { continuation in
            self.test(arg1: arg1) { object in
              continuation.resume(returning: object)
            }
          }
        }
        """,
        macros: testMacros
    )
}

Once that is in place, let's add a breakpoint at return [] inside the expansion method and run the test.
Once we hit the breakpoint, run po functionDecl inside the debug console to get this long description:

FunctionDeclSyntax
├─attributes: AttributeListSyntax
│ ╰─[0]: AttributeSyntax
│   ├─atSignToken: atSign
│   ╰─attributeName: SimpleTypeIdentifierSyntax
│     ╰─name: identifier("AddAsync")
├─funcKeyword: keyword(SwiftSyntax.Keyword.func)
├─identifier: identifier("test")
├─signature: FunctionSignatureSyntax
│ ╰─input: ParameterClauseSyntax
│   ├─leftParen: leftParen
│   ├─parameterList: FunctionParameterListSyntax
│   │ ├─[0]: FunctionParameterSyntax
│   │ │ ├─firstName: identifier("arg1")
│   │ │ ├─colon: colon
│   │ │ ├─type: SimpleTypeIdentifierSyntax
│   │ │ │ ╰─name: identifier("String")
│   │ │ ╰─trailingComma: comma
│   │ ╰─[1]: FunctionParameterSyntax
│   │   ├─firstName: identifier("completion")
│   │   ├─colon: colon
│   │   ╰─type: FunctionTypeSyntax
│   │     ├─leftParen: leftParen
│   │     ├─arguments: TupleTypeElementListSyntax
│   │     │ ╰─[0]: TupleTypeElementSyntax
│   │     │   ╰─type: OptionalTypeSyntax
│   │     │     ├─wrappedType: SimpleTypeIdentifierSyntax
│   │     │     │ ╰─name: identifier("String")
│   │     │     ╰─questionMark: postfixQuestionMark
│   │     ├─rightParen: rightParen
│   │     ╰─output: ReturnClauseSyntax
│   │       ├─arrow: arrow
│   │       ╰─returnType: SimpleTypeIdentifierSyntax
│   │         ╰─name: identifier("Void")
│   ╰─rightParen: rightParen
╰─body: CodeBlockSyntax
  ├─leftBrace: leftBrace
  ├─statements: CodeBlockItemListSyntax
  ╰─rightBrace: rightBrace

Here you can see every component of the function declaration.
And now you can pick the individual piece you need and use it to create you Macro-generated code.

Retrieve first argument name

For example, if you need to retrieve the first argument name of the function, you will write:

let signature = functionDecl.signature.as(FunctionSignatureSyntax.self)
let parameters = signature?.input.parameterList
let firstParameter = parameters?.first
let parameterName = firstParameter.firstName // -> arg1

This is quite a long code just to retrieve a single string and it will be even more complex if you need to handle multiple function variations.
I think that Apple will improve this in the future, but for now let's stick with this.

Complete the implementation

Now, let's complete the AddAsync implementation.

if let signature = functionDecl.signature.as(FunctionSignatureSyntax.self) {
   let parameters = signature.input.parameterList

   // 1.
   if let completion = parameters.last,
      let completionType = completion.type.as(FunctionTypeSyntax.self)?.arguments.first,
   let remainPara = FunctionParameterListSyntax(parameters.removingLast()) {

   // 2. returns "arg1: String"
   let functionArgs = remainPara.map { parameter -> String in
      guard let paraType = parameter.type.as(SimpleTypeIdentifierSyntax.self)?.name else { return "" }
      return "\(parameter.firstName): \(paraType)"
   }.joined(separator: ", ")

   // 3. returns "arg1: arg1"
   let calledArgs = remainPara.map { "\($0.firstName): \($0.firstName)" }.joined(separator: ", ")

   // 4.
   return [
   """
   func \(functionDecl.identifier)(\(raw: functionArgs)) async -> \(completionType) {
      await withCheckedContinuation { continuation in
         self.\(functionDecl.identifier)(\(raw: calledArgs)) { object in
            continuation.resume(returning: object)
         }
      }
   }
   """
   ]
}

In this block of code we:

Retrieve the completion argument from the function signature
Parse the function arguments except the completion
Create the arguments that get passed into the called function
Compose the async function

Show custom errors

Macros allow you to show custom errors to the user.
For example, in case the user placed the macro on a struct but that macro can only be used with functions.
In this case, you can throw an error and it will be automatically shown in Xcode.

enum AsyncError: Error, CustomStringConvertible {

  case onlyFunction

  var description: String {
    switch self {
    case .onlyFunction:
      return "@AddAsync can be attached only to functions."
    }
  }
}

// Inside `expansion` method. 
guard let functionDecl = declaration.as(FunctionDeclSyntax.self) else {
   throw AsyncError.onlyFunction // <- Error thrown here
}

Test Macro usage

To test the behaviour of the AddAsync macro.
Go to the main.swift file and add:

struct AsyncFunctions {

  @AddAsync
  func test(arg1: String, completion: (String) -> Void) {

  }
}

func testing() async {
  let result = await AsyncFunctions().test(arg1: "Blob")
}

As you can see the build completes with success.
!WARNING The autocompletion may not show the generated async function.

Show Macro generated code

To expand a Macro in code and see the automatically generated code, right click on the Macro and choose Expand Macro from the menu.
!WARNING The Expand Macro seems to not work always in Xcode 15.0 beta (15A5160n).

Breakpoint

Code generated by Macros can be debugged by adding breakpoints as you normally would.
To do this, right click on a Macro and choose Expand Macro from the menu.
Then add a breakpoints at the line you wish to debug.

Conclusion

Congratulations! You just created your first Macro.
Check out here the complete code.
As you saw, so far Macro implementations can be quite long event to perform a simple task.
But once you wrap your head around, they can be really useful and they can save you a lot of boilerplate code.
Macros are still in Beta so I think Apple will improve them by the time they will be available publicly.
Thank you for reading

Introducing SwiftData the successor of CoreData

Francesco Leoni — Wed, 14 Jun 2023 08:47:31 +0000

Here you can find this articles and many more about iOS and macOS Development.

SwiftData is a framework for data modelling and management.
It's built on top of CoreData's persistence layer, but with an API completely redesigned and reimagined for Swift.
SwiftData provides also support for undo and redo automatically.
And if your app have shared container enabled, SwiftData automatically makes data directly accessible by widgets using the same APIs.
Now, let's see how it works.

Models

First we need to create the models that we want to persist.
To create a model you need to mark the class with the Macro @Model.
SwiftData includes all non-computed properties of a class as long as they use compatible types. So far, SwiftData supports types such as Bool, Int and String, as well as structures, enumerations, and other value types that conform to the Codable protocol.
So, let's create the Folder and Note models.

@Model
final class Folder {

  @Attribute(.unique)
  var id: String = UUID().uuidString
  var name: String
  var creationDate: Date
  var notes: [Note] = []

  init(name: String) {
    self.name = name
    self.creationDate = .now
  }
}

@Model
final class Note: Decodable {

  @Attribute(.unique)
  var id: String = UUID().uuidString
  var text: String

  init(text: String) {
    self.text = name
  }

Create a model class that contains all the properties you wish to persist
Mark the classes with the Macro @Model
Optionally, add Macros (@Attribute, @Relationship, @Transient) to the property that need them

Creating models is as simple as that.

WARNING: As for now, if you declare an array of objects is likely you will get an error like Ambiguous use of 'getValue(for:)'. This is a bug in Xcode 15.0 beta that I think will be fixed on final version of Xcode. For now, just remove the @Model from the Note class and add @Transient() to notes property.

Model attributes

Properties in the @Model can have Macros attached to them that will defined their behaviour.
Currently there are 3 types of macros: @Attribute, @Relationship, @Transient.

@Attribute

This Macro alters how SwiftData handles the persistence of a particular model property.
This is commonly used to mark a property as primary key, as we did for Folder.id.

@Attribute(.unique) 
var id: String

But there are many other options:

encrypt: Stores the property’s value in an encrypted form.
externalStorage: Stores the property’s value as binary data adjacent to the model storage.
preserveValueOnDeletion: Preserves the property’s value in the persistent history when the context deletes the model.
spotlight: Indexes the property’s value so it can appear in Spotlight search results.
transformable: Transforms the property’s value between an in-memory form and a persisted form.
transient: Enables to the context to disregard the property when saving the model.
unique: Ensures the property’s value is unique across all models of the same type. ### @Relationship By default if you declare a property whose type is also a model, SwiftData manages the relationship between these models automatically. But if you want to customise its behaviour, you can use the @Relationship Macro.

@Relationship(.cascade) 
var notes: [Note] = []

This way if the Folder is deleted, all of its notes are deleted too.
This Macro defines the behaviour that in CoreData was named Delete Rule.

NOTE: Both @Attribute and @Relationship support the renaming of the argument in case you want to preserve the original name of the property.

@Transient

By default SwiftData persist all non-computed properties inside the model, but if you don't need to persist a specific property, you can add the @Transient Macro to that property.

@Transient 
var someTempProperty: String

The model container

Before using these models, we need to tell SwiftData which models to persist.
To do this there is the .modelContainer modifier. To use it you simply pass all the models you want to persist.

@main
struct NoteBookApp: App {

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: [Folder.self]) // <-
    }
}

Here we pass only the Folder class because SwiftData knows that it has to persist also Note since there is a relationship between the two classes.
The .modelContainer modifer allows you to specify some options.

inMemory: Whether the container should store data only in memory.
isAutosaveEnabled: If enabled you don't need to save changes.
isUndoEnabled: Allows you to undo or redo changes to the context.
onSetup: A callback that will be invoked when the creation of the container has succeeded or failed.

NOTE: If you model contains a relationship to another model, you can omit the destination model.

Saving models

Now, we are ready to use SwiftData.
Let's see how to save models.
First we need to get the context, to do this we use the @Environment(\.modelContext) wrapper.

@Environment(\.modelContext) private var context

Next, once we have the context, we create the object we want to save and we insert it into the context.

let folder = Folder(name: "Trips")
context.insert(folder)

If we have enabled the autosaving while creating the container we don't have to do anything else.
Otherwise we need to save the context.

do {
   if context.hasChanges {
      context.save()
   }
} catch {
   print(error)
}

Fetching models

To fetch existing models, SwiftData provides the @Query wrapper.
This wrapper allows you to sort, filter and order the result of the query.

@Query(filter: #Predicate { $0.name != "" },
       sort: \.name,
       order: .forward) 
var folders: [Folder]

Here we query by:

Filter folders that have non-empty name
Sort them by the name property
Order them ascending

Or, we can use a FetchDescriptor.

extension FetchDescriptor {

  static var byName: FetchDescriptor<Folder> {
    var descriptor = FetchDescriptor<Folder>(
        predicate: #Predicate { $0.id != "" },
        sortBy: [SortDescriptor(\.name)]
    )
    descriptor.fetchLimit = 50
    descriptor.includePendingChanges = true
    return descriptor
  }
}

@Query(.byName) 
var items: [Folder]

This way we can reuse the FetchDescriptor for as many queries as we need.

Updating models

To update a model we just need to change the value of the property we want and if autosave is enabled that's all.

folder.name = "New name"

Otherwise we need to save the context.

Deleting models

To delete a model is just as simple as to create one.
We get the instance of the object to delete and we pass it to the context.

context.delete(model)

Conclusion

SwiftData really simplifies the usage of CoreData, making it less prone to errors.
Of course this is still in Beta so there will be changes and improvements, but so far I really enjoyed playing with it.
Hope this will help developers speed up their workflow to persist data and reduce crashes.
Thank you for reading!
What are you thoughts about this? Tweet me @franceleonidev and share your opinion.

Combine CoreData and SwiftUI

Francesco Leoni — Fri, 09 Jun 2023 15:26:15 +0000

Recently I had to build an app using SwiftUI and CoreData.
I thought CoreData was used almost as you would use it with UIKit, but apparently there are some differences.
This guide is intended as a summary of my experience using CoreData combined with SwiftUI. If I will find other aspects, I will add them to this guide.
So, without further ado, let's begin.

Set-up

This is a pretty straightforward part.

If you start a new project you can check the 'Use Core Data' option and 'Host in CloudKit' if you want to save your users data to the cloud. In this case XCode will take care of setting up the project for you. (For the CloudKit part will need to do some extra steps).
If you have already a project you'll need to create a Persistence.swift file and a swift file where you initialise the CoreData stack. (You can even create a new project following the previous step, and copy the Persistence.swift file generated by XCode to your project.

Setup the @main app

Now that you have your project, to be able to use CoreData within your Views, you need to pass the managedObjectContext down you view hierarchy.
Usually this is done in your App.swift file.

@main
struct ExampleApp: App {

  let persistenceController = PersistenceController.shared

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environmentObject(persistenceController)
        .environment(\\.managedObjectContext, persistenceController.container.viewContext)
    }
  }
}

Personally I pass, as an .environmentObject, the PersistenceController itself. Because I like to keep all the CRUD logic inside that struct, but that's up to you. If you want to do so you need to make your PersistenceController struct conform to ObservableObject.
Great, now you're able to create, read, update and delete NSManagedObjects in your Views.

TIP: PersistenceController (here is an exemple) is the struct that XCode generates automatically for you when you start a new project with the 'Use Core Data' option checked.

Operating with CoreData

To operate with CoreData in your View you need to access the NSManagedObjectContext. To do so, you have two options:

Using the @Environment wrapper in your Views

@Environment(\\.managedObjectContext) private var viewContext

Using the @EnvironmentObject wrapper to get your controller, and from it you can access the viewContext or CRUD methods

@EnvironmentObject private var persistenceController: PersistenceController

Saving the context

You can save the context using the .save() method of NSManagedObjectContext. Before saving the context you can check whether there are some changes, and save it only if they are present.

do {
  if container.viewContext.hasChanges {
    try container.viewContext.save()
  }
} catch {
  print(error)
}

Saving objects

To save a NSManagedObject you first need to instanciate it and than configure its properties. And then save the context.

let note = Note(context: container.viewContext)
note.id = id
note.text = text
note.folder = folder
note.creationDate = Date()
saveContext()

TIP: You can animate this insertion wrapping this code inside the withAnimation function of SwiftUI.

Fetching objects

Now the fetching part, this is where I found the most difficulties. Let's start right away.
To fetch objects in SwiftUI the most convenient way of doing it is using the @FetchRequest or @SectionedFetchRequest wrappers, in every single View you need to read from CoreData.

WARNING: Passing fetched objects between Views will break the automatic updates in case you add, edit or delete objects. (If you know a way to pass fetch objects without breaking the updates let me know and I will update this guide)

So you need to add a @FetchRequest in every View you need CoreData objects and automatic updates. I know it is a bit annoying but it will be worth it.
So, with that said the code is the following:

@FetchRequest(entity: Object.entity(),
              sortDescriptors: [NSSortDescriptor],
              predicate: NSPredicate,
              animation: .default)
var objects: FetchedResults<Object>

Or, if you want your objects grouped by a property:

@SectionedFetchRequest(entity: Object.entity(),
                       sectionIdentifier: \\Object.property,
                       sortDescriptors: [NSSortDescriptor],
                       predicate: NSPredicate,
                       animation: .default)
var sections: SectionedFetchResults<YourSectionType, Object>

To use these sections you just pass them to a List or ForEach, and then to another ForEach.

List(sections) { section in
  Section(section.id) {
    ForEach(section) { object in
      // Configure your view with the object
    }
  }
}

TIP: If you use @SectionedFetchRequest with sorting you may need to specify two sort descriptor. The first will sort the sections and the second one will take care of the objects inside each section. This feature is really useful and requires very little effort.

Using @FetchRequest or @SectionedFetchRequest wherever you add, update or delete an object, the views are automatically updated.
Now, if you need to use a @FetchRequest with a NSPredicate that has a parameter passed from the parent View, I found that the next option works wonderfully.

@FetchRequest
var objects: FetchedResults<Object>

init(id: ID) {
  _objects = FetchRequest<Object>(predicate: NSPredicate(format: "id == %@", id))
}

This way you can pass your parameter in the init and use it to filter your results while keeping the automatic updates. The same goes for @SectionedFetchRequest.

Updating objects

To update a NSManagedObject you will need to have the NSManagedObject to update, fetched as described before and update its properties. And then save the context.

note.text = newText
note.folder = newFolder
saveContext()

Deleting objects

To delete a NSManagedObject you will need to have the NSManagedObject to update, fetched as described before and delete it.

viewContext.delete(object)

I didn't explained every single CRUD method of CoreData like batch insertion and deletion since this guide is focused on the interaction between CoreData and SwiftUI. Every NSManagedObjectContext method, background context, performAndAwait, … behaves exactly like it does with UIKit.

Conclusion

That's all I have discovered so far about CoreData used with SwiftUI. This guide will be constantly updated.
If you want to suggest a better way of doing something, leave a comment and I will update this guide with the best option.
I hope I helped you with you journey with SwiftUI and iOS development.
See you in the next guide!

If you would like to support my work and see this guide in action check out BrainDump - Notes & Writing
Thank you 🙏

SwiftyLion

This article was originally published on SwiftyLion. Head over there if you like this post and want to read others like it.