Swift's reflection capabilities are based around a struct called Mirror. You create a mirror for a particular subject and the mirror will then let you query it.

Before we do that, let's define a simple data structure that we can use as our subject.

import Foundation.NSURL

public class Store {
    let storesToDisk: Bool = true
}
public class BookmarkStore: Store {
    let itemCount: Int = 10
}
public struct Bookmark {
   enum Group {
      case Tech
      case News
   }
   private let store = {
       return BookmarkStore()
   }()
   let title: String?
   let url: NSURL
   let keywords: [String]
   let group: Group
}

let aBookmark = Bookmark(title: "Appventure", url: NSURL(string: "appventure.me")!, keywords: ["Swift", "iOS", "OSX"], group: .Tech)

The easiest way of creating a mirror is the reflecting initializer:

public init(reflecting subject: Any)

Lets use it with our aBookmark struct:

let aMirror = Mirror(reflecting: aBookmark)
print(aMirror)
// prints : Mirror for Bookmark

So this creates a Mirror for Bookmark. As you can see, the type of the subject is Any. This is the most general type in Swift. Anything under the Swift Sun is at least of type Any ¹. So this makes the mirror compatible with struct, class, enum, Tuple, Array, Dictionary, set, etc.

There are three additional initializers in the Mirror struct, however those are mostly used for circumstances where you'd want to provide your own, custom mirror. We will explain those additional initializers below when we discuss custom mirrors.

The Mirror struct contains several types to help you identify the information you'd like to query.

The first one is the DisplayStyle enum which tells you the type of the subject:

public enum DisplayStyle {
    case Struct
    case Class
    case Enum
    case Tuple
    case Optional
    case Collection
    case Dictionary
    case Set
}

Those are the supported types of the reflection API. As we saw earlier, reflection only requires an Any type, and there're many things in the Swift standard library that are of type Any but aren't listed in the DisplayStyle enum above. What happens when you try to reflect over one of those, say a closure?

let closure = { (a: Int) -> Int in return a * 2 }
let aMirror = Mirror(reflecting: closure)

In this case, you'd get a mirror, but the DisplayStyle would be nil ²

There's also a typealias for the child elements of a Mirror:

public typealias Child = (label: String?, value: Any)

So each child consists out of an optional label and a value of type Any. Why would the label be an Optional? If you think about it, it makes sense, not all of the structures that are supported by reflection have children with names. A struct has the property's name as the label, but a Collection only has indexes, not names. Tuples are a little bit special. In Swift values in tuple could have optional labels. Doesn't matter if value in tupple is labeled or not, in reflection tuple will have labels ".0", ".1" and so on.

Next up is the AncestorRepresentation enum ³:

public enum AncestorRepresentation {
    /// Generate a default mirror for all ancestor classes.  This is the
    /// default behavior.
    case Generated
    /// Use the nearest ancestor's implementation of `customMirror()` to
    /// create a mirror for that ancestor.      
    case Customized(() -> Mirror)
    /// Suppress the representation of all ancestor classes.  The
    /// resulting `Mirror`'s `superclassMirror()` is `nil`.
    case Suppressed
}

This enum is used to define how superclasses of the reflected subject should be reflected. I.e. this is only used for subjects of type class. The default (as you can see) is that Swift generates an additional mirror for each superclass. However, if you need more flexibility here, you can use the AncestorRepresentation enum to define how superclasses are being mirrored. We will have a look at that further below.

So we have our aMirror instance variable that reflects our aBookmark of type Bookmark subject. What do we do with it?

These are the available properties / methods on a Mirror:

• let children: Children: The child elements of our subject
• displayStyle: Mirror.DisplayStyle?: The display style of the subject
• let subjectType: Any.Type : The type of the subject
• func superclassMirror() -> Mirror?: The mirror of the subject's superclass

In the next step, we will analyze each of these.

Imagine we're working at the newest, hot, tech startup: Books Bunny. We offer an Artificial Intelligence with a browser plugin that automatically analyses all the sites that the user visits and automatically bookmarks the relevant urls.

It's 2016, Swift is already open source, so our server backend is obviously written in Swift. Since we have millions of site visits active in our system at a time, we'd like to use structs for the analysis part of each site that a user visits. However, if our AI decides that this is worthy of a bookmark, we'd like to use CoreData to store this type in a database.

Now, we don't want to write custom serialization to Core Data code whenever we introduce a new struct. Rather, we'd like to develop this in a way so that we can utilize it for all future structs we develop.

So, how do we do that?

Remember, we have a struct and want to automatically convert this to NSManagedObject (Core Data).

If we want to support different structs or even types, we can implement this as a protocol and then make sure our desired types conform to it. So which functionality should our imaginary protocol offer?

• First, it should allow us to define the name of the Core Data Entity that we want to create
• Second, it should have a way to tell it to convert itself to an NSManagedObject

Our protocol could look something like this:

protocol StructDecoder {
    // The name of our Core Data Entity
    static var EntityName: String { get }
    // Return an NSManagedObject with our properties set
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject
}

The toCoreData method uses the new Swift 2.0 exception handling to throw an error, if the conversion fails. There're several possible error cases, which are outlined in the ErrorType enum below:

enum SerializationError: ErrorType {
    // We only support structs
    case StructRequired
    // The entity does not exist in the Core Data Model
    case UnknownEntity(name: String)
    // The provided type cannot be stored in core data
    case UnsupportedSubType(label: String?)
}

We have three error cases that our conversion has to look out for. The first one is that we're trying to apply it to something that is not a struct. The second is that the entity we're trying to create does not exist in our Core Data Model. The third is that we're trying to write something into Core Data which can not be stored there (i.e. an enum).

Let's create a struct and add protocol conformance:

struct Bookmark {
   let title: String
   let url: NSURL
   let pagerank: Int
   let created: NSDate
}

Next, we'd like to implement the toCoreData method.

We could, of course, write this anew for each struct, but that's a lot of work. Structs do not support inheritance, so we can't use a base class. However, we can use a protocol extension to extend to all conforming structs:

extension StructDecoder {
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject {
    }
}

As this extension is being applied to our conforming structs, this method will be called in the structs context. Thus, within the extension, self refers to the struct which we'd like to analyze.

So, the first step for us is to create an NSManagedObject into which we can then write the values from our Bookmark struct. How do we do that?

Core Data is a tad verbose, so in order to create an object, we need the following steps:

1. Get the name of the entity which we'd like to create (as a string)
2. Take the NSManagedObjectContext, and create an NSEntityDescription for our entity
3. Create an NSManagedObject with this information.

When we implement this, we have:

// Get the name of the Core Data Entity
let entityName = self.dynamicType.EntityName

// Create the Entity Description
// The entity may not exist, so we're using a 'guard let' to throw 
// an error in case it does not exist in our core data model
guard let desc = NSEntityDescription.entityForName(entityName, inManagedObjectContext: context)
    else { throw UnknownEntity(name: entityName) }

// Create the NSManagedObject
let managedObject = NSManagedObject(entity: desc, insertIntoManagedObjectContext: context)

Next up, we'd like to use the Reflection API to read our bookmarks properties and write it into our NSManagedObject instance.

// Create a Mirror
let mirror = Mirror(reflecting: self)

// Make sure we're analyzing a struct
guard mirror.displayStyle == .Struct else { throw SerializationError.StructRequired }

We're making sure that this is indeed a struct by testing the displayStyle property.

So now we have a Mirror that allows us to read properties, and we have a NSManagedObject which we can set properties on. As the mirror offers a way to read all children, we can iterate over them and set the values. So let's do that.

for case let (label?, value) in mirror.children {
    managedObject.setValue(value, forKey: label)
}

Awesome. However, if we try to compile this, it will fail. The reason is that setValueForKey requires an object of type AnyObject?, however our children property only returns a tuple of type (String?, Any) - i.e. our value is of type Any but we need an AnyObject. To solve this, we have to test the value for AnyObject conformance. This also means that we can throw an error if we receive a property with a type that does not conform to AnyObject (such as an enum, for example).

let mirror = Mirror(reflecting: self)

guard mirror.displayStyle == .Struct 
  else { throw SerializationError.StructRequired }

for case let (label?, anyValue) in mirror.children {
    if let value = anyValue as? AnyObject {
	managedObject.setValue(child, forKey: label)
    } else {
	throw SerializationError.UnsupportedSubType(label: label)
    }
}

Now, our setValueForKey method will only be called if and only if the child is of type AnyObject.

Now, the only thing left to do is return our NSManagedObject. The complete code looks like this:

extension StructDecoder {
    func toCoreData(context: NSManagedObjectContext) throws -> NSManagedObject {
	let entityName = self.dynamicType.EntityName

	// Create the Entity Description
	guard let desc = NSEntityDescription.entityForName(entityName, inManagedObjectContext: context)
	    else { throw UnknownEntity(name: entityName) }

	// Create the NSManagedObject
	let managedObject = NSManagedObject(entity: desc, insertIntoManagedObjectContext: context)

	// Create a Mirror
	let mirror = Mirror(reflecting: self)

	// Make sure we're analyzing a struct
	guard mirror.displayStyle == .Struct else { throw SerializationError.StructRequired }

	for case let (label?, anyValue) in mirror.children {
	    if let value = anyValue as? AnyObject {
		managedObject.setValue(child, forKey: label)
	    } else {
		throw SerializationError.UnsupportedSubType(label: label)
	    }
	}

	return managedObject
    }
}

That's it. We're converting our struct to NSManagedObject.

The first special init is tailor-made for collections:

public init<T, C : CollectionType where C.Generator.Element == Child>
  (_ subject: T, children: C, 
   displayStyle: Mirror.DisplayStyle? = default, 
   ancestorRepresentation: Mirror.AncestorRepresentation = default)

Compared to the init(reflecting:) initializer above, this one allows us to define much more details about the reflection process.

• It only works for collections
• We can set the subject to be reflected and the children of the subject (the collection contents)

The second can be used for a class or a struct.

public init<T>(_ subject: T, 
  children: DictionaryLiteral<String, Any>, 
  displayStyle: Mirror.DisplayStyle? = default, 
  ancestorRepresentation: Mirror.AncestorRepresentation = default)

Interesting to note, here, is that you provide the children (i.e. properties) of your subject as a DictionaryLiteral which is a bit like a dictionary only that it can be used directly as function parameters. If we implement this for our Bookmark struct, it looks like this:

extension Bookmark: CustomReflectable {
    func customMirror() -> Mirror {
	let children = DictionaryLiteral<String, Any>(dictionaryLiteral: 
	("title", self.title), ("pagerank", self.pagerank), 
	("url", self.url), ("created", self.created), 
	("keywords", self.keywords), ("group", self.group))

	return Mirror.init(Bookmark.self, children: children, 
	    displayStyle: Mirror.DisplayStyle.Struct, 
	    ancestorRepresentation:.Suppressed)
    }
}

If we do another performance measurement now, there's even a slight improvement:

But hardly worth the effort, as it defeats our initial purpose of reflecting over our struct's members.