Chapters
Chapters

Chapters

Hide chapters

Swift Internals

First Edition · iOS 26 · Swift 6.2 · Xcode 26

Before You Begin

Section 0: 5 chapters
Show chapters Hide chapters

Section I: Swift Fundamentals & Type System

Section 1: 3 chapters
Show chapters Hide chapters

Section II: Execution, Concurrency, & The Compiler

Section 2: 3 chapters
Show chapters Hide chapters

Section III: Scalable Architecture & Tooling

Section 3: 3 chapters
Show chapters Hide chapters

7. Metaprogramming
Written by Aaqib Hussain

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

Heads up... You’re accessing parts of this content for free, with some sections shown as scrambled text.

Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now

The word “meta” is actually a Greek term that is commonly used as a prefix today. It means “beyond” or “after.” Metaprogramming refers to going “beyond” just writing code that runs. It’s not about the app logic itself—like performing a network request, developing UI, or building business logic—but about the powerful practice of writing code that can generate, analyze, or transform another piece of code. This is where the Swift language becomes a tool to manipulate your codebase.

Why should you care? This is the ultimate weapon against boilerplate code. The repetitive code you copy-paste for equality conformance, JSON decoding, or test mocks is a major source of bugs and is difficult to maintain. Here, metaprogramming acts as a knight in shining armor, enabling you to write a single piece of code that generates other repetitive code, ensuring consistency from a single source of truth. It also powers the creation of expressive, human-readable Domain-Specific Languages (DSLs).

This chapter explores three distinct metaprogramming methods in Swift, each with its own trade-offs along the spectrum of runtime flexibility and compile-time safety. You’ll start with runtime inspection using Mirror, which lets you peek inside any type while your app is running. Next, you’ll learn about compile-time transformation with @resultBuilder, the engine that turns simple Swift into complex data structures. Finally, you’ll gain hands-on experience with Swift Macros, a feature that generates code during compilation, eliminating entire categories of boilerplate with a single line. This chapter isn’t about hammering nails; it’s about building the hammer.

The Magic Mirror: Runtime Reflection with Mirror

In standard programming, you write code that operates on data. You are aware of the variables, their types, properties, and methods during compilation. But what if you want to see it while your code is running? What if you want to write a generic inspector that can examine any object? Whether it’s a struct User, an enum NetworkError, or even a class you haven’t implemented yet.

This is a common feature also available in languages other than Swift. It’s called Reflection. It refers to a program’s ability to inspect its structure such as types, relationships, and properties at runtime. In Swift, the primary tool to effectively leverage this capability is Mirror.

What is Reflection?

Reflection is a kind of metaprogramming that happens only at runtime. Unlike compilation tools that validate code before execution, reflection examines your app’s objects in memory while they are active.

How to Use Mirror?

Using a Mirror is quite simple. You create a Mirror to reflect any instance you want to inspect.

struct User {
  let name: String
  let age: Int
}

let michael = User(name: "Michael Scott", age: 44)

// Create the mirror
let mirror = Mirror(reflecting: michael)

print("Inspecting \(mirror.subjectType):")
for child in mirror.children {
  let propertyName = child.label ?? "unknown"
  print("  - \(propertyName): \(child.value)")
}
// Output:
// Inspecting User:
//   - name: Michael Scott
//   - age: 44

Practical Use Case: Building a Generic prettyPrint

The best way to use Mirror is to create something useful with it. A common issue in debugging is printing complex objects, resulting in unreadable, jumbled output. You can use Mirror to write a generic function that uses reflection to recursively print any object with clear indentation.

func prettyPrint(_ value: Any, indent: Int = 0) {
    let mirror = Mirror(reflecting: value)
    
    // Base case: If the value has no children, just print the it directly.
    if mirror.children.isEmpty {
        print(value)
        return
    }
    
    // Determine if it's a collection to use [] instead of ().
    let isCollection = mirror.displayStyle == .collection || mirror.displayStyle == .set || mirror.displayStyle == .dictionary
    let open = isCollection ? "[" : "("
    let close = isCollection ? "]" : ")"
    
    // Print type name (if not a collection) and opening bracket.
    if !isCollection {
        print("\(mirror.subjectType)", terminator: "")
    }
    print(open)
    
    let childIndent = String(repeating: "  ", count: indent + 1)
    
    for child in mirror.children {
        // Always print indentation first
        print(childIndent, terminator: "")
        
        // If it has a label (like struct properties), print it.
        // Arrays usually don't have labels for their elements.
        if let label = child.label {
            print("\(label): ", terminator: "")
        }
        
        // Recurse for the value
        prettyPrint(child.value, indent: indent + 1)
    }
    
    // Print closing bracket with parents’ indentation.
    let footerIndent = String(repeating: "  ", count: indent)
    print("\(footerIndent)\(close)")
}

struct Company {
  let boss: User
  let employees: [User]
}

let dunderMifflin = Company(
  boss: User(name: "Michael", age: 44),
  employees: [
    User(name: "Jim", age: 33),
    User(name: "Dwight", age: 38)
  ]
)

prettyPrint(dunderMifflin)

Company(
  boss: User(
    name: Michael
    age: 44
  )
  employees: [
    User(
      name: Jim
      age: 33
    )
    User(
      name: Dwight
      age: 38
    )
  ]
)

The Limitations of the Mirror

While Mirror is a phenomenal tool, it comes with important trade-offs, especially compared to reflection in more dynamic languages.

Dynamic Lookups: @dynamicMemberLookup

@dynamicMemberLookup lets you intercept accesses to members that don’t exist at compile time.

What is @dynamicMemberLookup?

@dynamicMemberLookup is an attribute that you can apply to a struct, class, or enum. It fundamentally alters how the compiler handles property access on that type.

Applying the @dynamicMemberLookup Attribute

To fulfill the promise with the compiler, the type marked with @dynamicMemberLookup must implement a special subscript method: subscript(dynamicMember member: String). The String parameter represents the member name extracted from the dot syntax.

@dynamicMemberLookup
struct DynamicDictionary {
  private var data: [String: Any]
  
  init(_ data: [String: Any]) {
    self.data = data
  }
  
  // The required subscript
  subscript(dynamicMember member: String) -> Any? {
    print("Dynamic lookup for member: '\(member)'")
    return data[member]
  }
}

let user = DynamicDictionary(["name": "Jim Halpert", "age": 33])

// 1
let name = user.name
// 2
print(name)

Practical Use Case: A Type-Safe JSON Wrapper

The most common and powerful use case for a @dynamicMemberLookup is building a wrapper that makes JSON-style access cleaner and more ergonomic.

// The "Before" - Painful, nested casting
var userName: String?
if let userDict = json["user"] as? [String: Any] {
  if let nameValue = userDict["name"] as? String {
    userName = nameValue
  }
}

@dynamicMemberLookup
struct JSON {
  private var data: Any?
  
  init(_ data: Any?) {
    self.data = data
  }
  
  subscript(dynamicMember member: String) -> JSON {
    guard let dict = data as? [String: Any] else {
      return JSON(nil)
    }
    return JSON(dict[member])
  }
  
  var string: String? {
    return data as? String
  }
  
  var int: Int? {
    return data as? Int
  }
  
  var array: [JSON]? {
    guard let arr = data as? [Any] else { return nil }
    return arr.map { JSON($0) }
  }
}

// The "After" - Clean, chainable, and readable
let userData: [String: Any] = [
  "user": [
    "name": "Michael G. Scott",
    "age": 44
  ]
]

let json = JSON(userData)
let name = json.user.name.string
print(name) // Prints Optional("Michael G. Scott")

The DSL Factory: Mastering Result Builders

Inspecting objects during runtime is interesting; what’s even more exciting is working with powerful compile-time metaprogramming concepts. This is where the code’s structure is modified as it’s being compiled.

What is a Domain Specific Language (DSL)?

A Domain Specific Language (DSL) is a small language created for a specific task. Swift is a general-purpose language; you can use it to build anything, from watch apps to web servers. In contrast, a DSL is highly focused, offering a limited set of commands and a specific syntax that makes it very expressive for one particular domain.

// The "old" way (imperative)
let text = Text("Hello")
let image = Image("icon")
let stack = VStack()
stack.addArrangedSubview(text)
stack.addArrangedSubview(image)
return stack

// The DSL way (declarative)
VStack {
  Text("Hello")
  Image("icon")
}

Introducing @resultBuilder

So how does a simple list of views become a complex, combined view? The answer you’re looking for is the @resultBuilder attribute.

VStack {
  Text("Hello")
  Image("icon")
}

VStack(content: {
  let view1 = Text("Hello")
  let view2 = Image("icon")
  return ViewBuilder.buildBlock(view1, view2)
})

Using a Result Builder: buildBlock

To grasp the concept of this attribute, you’re going to build a simple example ArrayBuilder whose only job is to take a list of items and wrap them in an array.

@resultBuilder
struct ArrayBuilder<T> {
  // This is the most important method.
  // It takes a list of components and combines them.
  static func buildBlock(_ components: T...) -> [T] {
    print("buildBlock called with \(components.count) items")
    return components
  }
}

func buildArray<T>(@ArrayBuilder<T> content: () -> [T]) -> [T] {
  return content()
}

let numbers = buildArray {
  1
  2
  3
}

print(numbers)

buildBlock called with 3 items 
[1, 2, 3]

Adding Logic

A DSL that only supports static elements is limited. The real power of a result builder emerges when you add support for control flow, like if and else statements.

@resultBuilder
struct ArrayBuilder<T> {
  static func buildExpression(_ expression: T) -> [T] {
    print("buildExpression called")
    return [expression]
  }
  
  // 2. Accept variadic arrays and flatten them
  static func buildBlock(_ components: [T]...) -> [T] {
    print("buildBlock called with \(components.count) items")
    return components.flatMap { $0 }
  }
  
  // This enables: if condition { ... }
  static func buildOptional(_ component: [T]?) -> [T] {
    print("buildOptional called")
    return component ?? []
  }
}

var showExtra = false
let numbers = buildArray {
  1
  2
  if showExtra {
    3
  }
}

buildBlock called with 3 items 
[1, 2]

static func buildEither(first component: [T]) -> [T] {
  return component
}

static func buildEither(second component: [T]) -> [T] {
  return component
}

@resultBuilder
struct ArrayBuilder<T> {
  // 1. Normalize single items to arrays
  static func buildExpression(_ expression: T) -> [T] {
    print("buildExpression called")
    return [expression]
  }
  
  // 2. Accept variadic arrays and flatten them
  static func buildBlock(_ components: [T]...) -> [T] {
    print("buildBlock called with \(components.count) items")
    return components.flatMap { $0 }
  }
  
  // 3. Logic methods must now work with [T]
  static func buildOptional(_ component: [T]?) -> [T] {
    return component ?? []
  }
  
  static func buildEither(first component: [T]) -> [T] { return component }
  static func buildEither(second component: [T]) -> [T] { return component }
}

var showExtra = false
let numbers = buildArray {
  1
  2
  if showExtra {
    3
  } else {
    4
  }
}

[1, 2, 4]

Practical Use Case: Building a Simple HTMLBuilder

You can use what you’ve learned about result builders and put it into practical use by developing an expressive DSL for generating HTML strings. The goal is to write Swift that reads like HTML.

@resultBuilder
struct HTMLBuilder {
  static func buildBlock(_ components: String...) -> String {
    components.joined(separator: "\n")
  }
  
  static func buildOptional(_ component: String?) -> String {
    component ?? ""
  }
  
  static func buildEither(first component: String) -> String { component }
  static func buildEither(second component: String) -> String { component }
}

func html(@HTMLBuilder content: () -> String) -> String {
  "<html>\n\(content())\n</html>"
}

func body(@HTMLBuilder content: () -> String) -> String {
  "<body>\n\(content())\n</body>"
}

func p(_ content: String) -> String {
  "<p>\(content)</p>"
}

func h1(_ content: String) -> String {
  "<h1>\(content)</h1>"
}

let isLoggedIn = true

let myPage = html {
  body {
    h1("Welcome to our site!")
    if isLoggedIn {
      p("You are logged in.")
    } else {
      p("Please log in to continue.")
    }
    p("This is a DSL-powered website.")
  }
}

print(myPage)

<html>
<body>
<h1>Welcome to our site!</h1>
<p>You are logged in.</p>
<p>This is a DSL-powered website.</p>
</body>
</html>

The New Frontier: Swift Macros

For years, Swift developers have chased the Holy Grail of clean code: eliminating boilerplate. In pursuit of this, they have used inheritance, protocol extensions, and generic constraints to reduce repetition. Yet, you still find yourself writing CodingKeys manually at times, creating endless mocks for testing, or wrapping legacy completion handlers to work with async code.

What are Macros?

At its core, a macro is a compile-time transformation that can be invoked either as an attribute (attached macros) or as an expression (freestanding macros) to generate Swift code.

Macros vs. Mirror

You used Mirror to dynamically inspect a type’s properties (e.g., for JSON parsing or logging).

Macros vs. @resultBuilder

Result builders (introduced in SwiftUI) enable transforming a sequence of statements into a single value.

Type 1: Freestanding Macros

The first type of macro is a Freestanding Macro. They appear in your code as expressions that start with a hash symbol (#). They behave somewhat like functions, but instead of being executed at runtime, they expand at compile time into ordinary Swift expressions that may produce runtime values.

The Problem: Runtime Validation

Consider the common task of creating a URL from a string.

// The old way
let url = URL(string: "https://www.apple.com")!

The Solution: The #URL Macro

A freestanding macro can validate the string during compilation.

// For illustration, imagine a #URL macro:
let url = #URL("https://www.apple.com")

Type 2: Attached Macros

Another powerful category of macros is attached macros. These are identified by the @ symbol (e.g., @Observable, and @Model from SwiftData).

The Problem: Legacy Boilerplate

A significant challenge in modern iOS development is bridging the gap between legacy callback-based APIs and modern Swift Concurrency (async/await).

class NetworkService {
  func fetchUserProfile(id: String, completion: @escaping (Result<User, Error>) -> Void) {
    // complex legacy networking logic...
  }
}

The Solution: The @GenerateAsync Macro

You can create an attached macro called @GenerateAsync. When attached to a function, it analyzes the function signature, detects the completion handler, and automatically generates the async version.

class NetworkService {
  @GenerateAsync
  func fetchUserProfile(id: String, completion: @escaping (Result<User, Error>) -> Void) {
    // legacy logic
  }
}

// Generated by @GenerateAsync
extension NetworkService {
  func fetchUserProfile(id: String) async throws -> User {
    return try await withCheckedThrowingContinuation { continuation in
      self.fetchUserProfile(id: id) { result in
        continuation.resume(with: result)
      }
    }
  }
}

Why Macros are a Game-Changer

Swift Macros are more than just a convenience; they represent a fundamental shift in how Swift libraries can be designed.

The End of Boilerplate

The primary goal for developers is to write business logic, not boilerplate code. Macros address the boilerplate problem by allowing library creators to write foundational code once and have it automatically replicated by the compiler. From the @Observable macros in SwiftUI to SwiftData’s @Model, Apple already demonstrates that macros are becoming the standard for reducing code verbosity.

Consistency and Safety

Humans tend to make mistakes and copy-and-paste errors; compilers do not. When you manually conform to Codable or Equatable for complex types, you might overlook a property. A well-written macro won’t overlook a property, and it can enforce that generated code stays aligned with the source declaration.

White Box Magic

Historically, code-generation tools in iOS were opaque: you ran a script, and a file appeared. Swift macros are now integrated into Xcode. You can right-click a macro and select “Expand Macro” to see exactly what code is being generated. This transparency builds trust; you’re not relying on magic. Instead, you rely on code that you can see, debug, and understand.

Key Points

  • Metaprogramming is a technique for writing code that creates, examines, or modifies other code, rather than just executing application logic.
  • Metaprogramming is the best way to eliminate boilerplate, reduce copy-paste mistakes, and create a single source of truth for repetitive logic.
  • Mirror enables a program to examine its own structure (properties, types, and values) during execution.
  • You create a Mirror(reflecting: instance) to access the children property, which allows you to iterate over labels and values dynamically.
  • Mirror enables the creation of generic tools, such as a recursive prettyPrint function, that can handle any type without knowing its structure in advance.
  • Reflection in Swift is read-only (you cannot modify values) and is computationally expensive; it should be avoided in performance-critical loops.
  • @dynamicMemberLookup lets you access properties with dot syntax (for example, object.name), even if those properties aren’t available at compile time. The compiler converts dot-syntax calls into a specific subscript call: subscript(dynamicMember: String). It bridges the gap between Swift’s strict type safety and dynamic data, making it ideal for creating clean wrappers around JSON, dictionaries, or scripts.
  • @resultBuilder powers SwiftUI by allowing the creation of Domain-Specific Languages (DSLs) where code specifies what to do, not how to do it. This attribute converts a sequence of distinct statements (such as a list of Views) into a single combined value.
  • Every result builder must implement static func buildBlock(…), which specifies how components are combined.
  • To support logic like if and else within a DSL, the builder must implement methods such as buildOptional and buildEither.
  • Introduced in Swift 5.9, Macros run at compile time to create and insert new code into your source files, with no runtime reflection cost.
  • Unlike result builders, Macros interact with the Abstract Syntax Tree through SwiftSyntax, enabling them to examine types in detail and create entirely new declarations.
  • Freestanding macros stand alone (like #URL) and act as expressions that return a value or perform validation, effectively replacing runtime crashes with compile-time errors.
  • Attached macros are applied to declarations (like @GenerateAsync) and enhance code by adding new methods, properties, or conformances to existing types.

Where to Go From Here?

You have now stepped behind the curtain of the Swift language. Having been introduced to metaprogramming, you’ve progressed from simply using Apple’s tools to building your own. You understand that Mirror provides visibility during runtime inspection, @resultBuilder helps you create expressive DSLs, and Swift Macros enable code generation during compilation.

"Why waste time say lot word when few word do trick?"
6. Unsafe Swift
8. Architectural Dynamics: Modularization & Linking
Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2026 Kodeco Inc.

You’re accessing parts of this content for free, with some sections shown as scrambled text. Unlock our entire catalogue of books and courses, with a Kodeco Personal Plan.

Unlock now