Swift Metaprogramming: A Practical Guide to Runtime Self-Inspection

Overview

Metaprogramming in Swift lets your code inspect its own structure during execution. Unlike compile-time macros, runtime reflection enables you to build generic tools that work with any type, such as debug printers, JSON serializers, or chainable dynamic APIs. This guide covers the core mechanisms: the Mirror type for reflection and the @dynamicMemberLookup attribute for dot-syntax access to dynamic data. By the end, you'll know how to create a generic property inspector and a chainable API over loosely typed data.

These techniques are especially useful for frameworks, logging utilities, and data mapping layers. They trade some compile-time safety for flexibility, but when used judiciously, they significantly reduce boilerplate.

Prerequisites

• Basic proficiency in Swift (structs, classes, protocols, generics)
• Xcode 12 or later (or any Swift 5.3+ environment)
• Familiarity with Any and optional types
• (Optional) Understanding of Codable for contrast

Step-by-Step Guide

1. Inspecting Types with Mirror

The Mirror type provides a representation of any value’s structure. Create one with Mirror(reflecting: yourInstance) and access its children property, which is a collection of label-value pairs (e.g., property names and values).

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

let person = Person(name: "Alice", age: 30)
let mirror = Mirror(reflecting: person)

for child in mirror.children {
    if let label = child.label {
        print("\(label): \(child.value)")
    }
}
// Output:
// name: Alice
// age: 30

Notice that child.value is of type Any. You can conditionally cast it to inspect deeper.

2. Building a Generic Inspector

Using generics and Mirror, you can write a function that prints the properties of any type. Handle nesting by recursively inspecting values that themselves have a Mirror (i.e., are not primitive).

func inspect(_ value: T, indent: Int = 0) {
    let mirror = Mirror(reflecting: value)
    guard !mirror.children.isEmpty else {
        // Primitive or empty – simply print the value
        print(String(repeating: "  ", count: indent) + "\(value)")
        return
    }
    for (label, child) in mirror.children {
        let prefix = String(repeating: "  ", count: indent)
        if let label = label {
            print("\(prefix)\(label):")
        } else {
            print(prefix + "(unnamed):")
        }
        let childMirror = Mirror(reflecting: child)
        if childMirror.children.isEmpty {
            print(prefix + "  \(child)")
        } else {
            inspect(child, indent: indent + 1)
        }
    }
}

struct Address {
    let street: String
    let zip: String
}
struct Employee {
    let name: String
    let address: Address
}

let employee = Employee(name: "Bob", address: Address(street: "123 Main", zip: "45678"))
inspect(employee)
// Output:
// name:
//   Bob
// address:
//   street:
//     123 Main
//   zip:
//     45678

This inspector works with any struct or class. Add handling for collections (Arrays, Dictionaries) to make it more robust.

3. Dynamic Member Lookup for Chainable APIs

The @dynamicMemberLookup attribute allows dot‑syntax access to members that are not known at compile time. You implement a subscript that takes a string key (the member name) and returns a value (often Any?).

@dynamicMemberLookup
struct JSONWrapper {
    private var data: [String: Any]

    init(_ data: [String: Any]) {
        self.data = data
    }

    subscript(dynamicMember member: String) -> Any? {
        return data[member]
    }
}

let json = JSONWrapper(["name": "Carol", "age": 28])
print(json.name as Any)   // Prints: Optional("Carol")
print(json.age as Any)    // Prints: Optional(28)

Notice that json.name is valid even though name isn't a real property. If the key doesn’t exist, you get nil. Combine this with Mirror to create a fully dynamic model that can inspect itself or even mutate values.

4. Combining Mirror and @dynamicMemberLookup

For maximum flexibility, you can build a type that both inspects its own structure and allows dot‑syntax access. For example, a dynamic data container that reports its fields via reflection:

@dynamicMemberLookup
struct DynamicModel {
    private var storage: [String: Any]

    init(_ dict: [String: Any]) {
        self.storage = dict
    }

    subscript(dynamicMember member: String) -> Any? {
        get { return storage[member] }
        set { storage[member] = newValue }
    }

    // Use Mirror in an instance method
    func propertyNames() -> [String] {
        return Array(storage.keys)
    }
}

var model = DynamicModel(["title": "Swift", "version": 5.9])
print(model.title as Any)   // Optional("Swift")
model.rating = 4.8          // New key added
print(model.propertyNames()) // ["title", "version", "rating"]

This pattern is powerful when working with JSON or other dynamic sources: you can access fields without writing explicit keys, and you can enumerate all fields at runtime.

Common Mistakes

• Forgetting the @dynamicMemberLookup attribute – Without it, the subscript won't be triggered by dot syntax. You’ll get a compile error.
• Relying on Mirror for critical logic – Reflection is not free. Overusing it can hurt performance, especially in loops. Use it only where compile‑time types are insufficient.
• Assuming child order – Mirror.children order is not guaranteed. If you need a specific order, sort the labels yourself.
• Ignoring optional values – When printing or inspecting, optional values may appear as Optional(value). Use String(describing:) or conditional unwrapping for cleaner output.
• Overcomplicating recursion – In the generic inspector, be careful with recursive structures (e.g., linked lists). Add a depth limit to prevent infinite loops.

Summary

Metaprogramming in Swift – using Mirror and @dynamicMemberLookup – lets you write code that inspects and interacts with its own structure at runtime. You can build generic inspectors, debug utilities, and flexible APIs over dynamic data with minimal boilerplate. While these techniques sacrifice some type safety and performance, they provide immense flexibility for frameworks and data‑driven applications. Experiment with combining them to create your own reflection‑based tools.