Saving Files with Codable

@IBAction func saveStuff(_ sender: NSButton) {
let savePanel = NSSavePanel()
savePanel.isExtensionHidden = false
savePanel.canSelectHiddenExtension = true
savePanel.allowedFileTypes = ["unicorn"] let userChoice = savePanel.runModal()
switch userChoice {
case .OK:
if let panelResult = savePanel.url {

//all saving functions will be called here

}
case .cancel:
print("saving cancelled")
default:
break
}
}

@IBAction func loadStuff(_ sender: NSButton) {
let openPanel = NSOpenPanel()
let userChoice = openPanel.runModal()
switch userChoice{
case .OK :
if let panelResult = openPanel.url {

//all loading functions will be called here

}
case .cancel :
print("loading cancelled")
default:
break
}
}

(The reason for a default statement lies in NSApplication.ModalResponse)

1) Proof of concept.

As demonstrated in the NSSavePanel/NSOpenPanel post, we’ll use the write to file method of Swift Strings to save a string to file and read it again. Create the following two functions:

func saveString(to saveURL: URL){

let myString = inputFld.stringValue
do {
try myString.write(to: saveURL, atomically: true, encoding: .utf8)
// most basic encoding; used here to allow the file to be read more easily by almost any text processing app
} catch {
print(error)
}
}
}

func loadString(from loadURL: URL){
do {
let myUnicorn = try String.init(contentsOf: loadURL)
outputLabel.stringValue = myUnicorn.text
} catch {
print(error)
}
}

and add the following to the save and load functions:
//1) Saving a string to file
saveString(to: panelResult)

//1) Loading a string from file
loadString(from: panelResult)

2) So far, so good. We have fully functioning open and save panels, which allow users full control over where they want to save files; and we have a robust framework for loading and saving, even though all we do with errors is print them to console.

We now make a brief detour into the land of NSCoding.

Until Summer 2017, the NSCoding protocol was responsible for encoding and decoding your objects. And I’m meaning ‘objects’ in the narrowest possible sense: in order to conform to NSCoding, your class had to inherit from NSObject. This created a certain amount of friction: on the one hand, you are encouraged to use value types (structs) and enums in your code… and then you need to provide initialisers for these that are based on Foundation types, so you can save your size: .small property as “small”, pass that string to your initialiser, and create a .small value from it.

Possible, but not a lot of fun.

2a) Here’s the most basic NSCoding-compliant unicorn:

class UnicornObject: NSObject, NSCoding {
var text: String = ""

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

required convenience init?(coder aDecoder: NSCoder) {
guard let text = aDecoder.decodeObject(forKey: "unicornText") as? String else {
print("no unicorns here")
return nil
}
self.init(text: text)
}

func encode(with aCoder: NSCoder) {
aCoder.encode(self.text, forKey: "unicornText")
}

}

(NSCoding has a long list of ‘encodeX/decodeX’ methods, so there’s a little more to watch out for. For a good article on the topic, see http://nshipster.com/nscoding/ I’m borrowing a LOT of their syntax, because it’s so elegant. Making the required coder init a _convenience_ one solved a lot of awkwardness.)

2b) Comment out the string-saving/loading functions, and add the following two calls:

//2) NSCoding
saveCodedUnicorn(to: panelResult)

// 2) NSCoding
loadCodedUnicorn(from: panelResult)

and create a variable and the two functions:

var myUnicorn = UnicornObject(text: "This is an old-fashioned unicorn. It conforms to NSCoding.")

func saveCodedUnicorn(to saveURL: URL){
NSKeyedArchiver.archiveRootObject(myUnicorn, toFile: saveURL.path)
outputLabel.stringValue = "Unicorn saved"
}

func loadCodedUnicorn(from loadURL: URL){
guard let unicorn = NSKeyedUnarchiver.unarchiveObject(withFile: loadURL.path) as? UnicornObject else {return}
outputLabel.stringValue = unicorn.text
}

(it is far more common to have arrays or other collections as root objects, but I wanted the simplest possible case here.)

3) Let’s play that again, with Codable:

3a)
struct ModernUnicorn: Codable {

var text: String = "I am the model of a codable unicorn."

}

That looks great! I love it. So little boilerplate! So easy to remember!

… and then I fell into the rabbit hole of ‘ok, I’ve got codable items, but what do I actually DO with them?’

If the answer is ‘write to JSON’, you’re in luck. You can find lots of tutorials for JSON. What you cannot find – at least, what I could not find between June 2017 and February 2018 – is one single snippet of code by Apple that shows you how to write Codable to a file. (The Archives and Serializations Programming Guide, last updated 17/2/2012, does not mention Codable)

3b) We can try our luck with NSKeyedArchiver and NSKeyedUnarchiver. Spoiler: the archiveRootObject and unarchiveObject(withFile:) methods don’t work with Codable.

3c) This article and the gist linked here go down the route of NSKeyedArchiver using encodeEncodable(forKey:) respectively NSKeyedUnarchiver.decodeTopLevelDecodable(forKey:)

From their signatures (and the fact that they throw with Swift 3+ syntax), we can conclude that these are meant to be used with Codable, hence:

var modernUnicorn = ModernUnicorn()

func saveModernUnicorn(to saveURL: URL){

//set modernUnicorn.text to any value you like. I'm lazy here.

let archiver = NSKeyedArchiver()

do {
try archiver.encodeEncodable(modernUnicorn, forKey: NSKeyedArchiveRootObjectKey)
try archiver.encodedData.write(to: saveURL)

} catch {
print(error)
}

outputLabel.stringValue = "Modern unicorn saved"
}

func loadModernUnicorn(from loadURL: URL){

do {
let unicornData = try Data.init(contentsOf: loadURL)
let unarchiver = NSKeyedUnarchiver(forReadingWith: unicornData)
if let resurrectedUnicorn = try unarchiver.decodeTopLevelDecodable(ModernUnicorn.self, forKey: NSKeyedArchiveRootObjectKey) {
print("Unicorn resurrection was successful")
modernUnicorn = resurrectedUnicorn
}
} catch {
print(error)
}

outputLabel.stringValue = modernUnicorn.text
}

The amount of boilerplate necessary to write to use Codable instead of NSCoding in out trivial example is about equal; but as long as you don’t need to do any customisation, objects with more properties will win out under Codable. But it’s useful to look at what’s under the hood to allow more customisation.

Let’s create a VerboseUnicorn struct, the corresponding var verboseUnicorn = VerboseUnicorn(), and change all references to ModernUnicorns to VerboseUnicorn.

struct VerboseUnicorn: Codable {
var text: String = "Too many words."

init(){
}
}

4a) Coding Keys

Even with NSCoding, it’s good practice to use an enum to provide coding keys instead of having to type strings: if I type ‘text’ in my encoding method, and ‘unicornText’ in init(coder:), I create a problem. A CodingKeys enum would give us code completion; problem solved.

add

enum CodingKeys: String, CodingKey {
case text = "unicornText"
}

to your VerboseUnicorn class. CodingKeys can be either String or Int; for most cases – particularly if you choose an output format like JSON that you can examine manually to see whether your save has been successful – Strings render the output more readable.

The most common use for Coding keys was JSON encoding: JSON frequently uses snake_case for property names (lowercase words separated by underscores , while Swift prefers camelCase (names closed up with subsequent nouns starting with capitals). This is, in fact, so common that in Swift 4.1 JSONEncoder now has a .convertToSnakeCase decoding strategy, with a corresponding .convertFromSnakeCase for JSONDecoder.

4b) Encodable/Decodable conformation
Encodable:
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encode(text, forKey: .text)
}
(container needs to be a var since encode(forKey:) is a mutating function.)

Decodable:
init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.text = try container.decode(String.self, forKey: .text)
}

(I had to type both of these out using the signatures in the Encodable/Decodable protocol documentation.)

Build and run. The code from Section 3 – now amended for Verbose Unicorns – should work exactly the same.
You need to include all of the keys you want to encode in the CodingKeys enum; but if you have properties you do not wish to save – for instance, because you will be updating them with a network call – you can simply leave them out of the CodingKeys enum, even if you rely on the compiler’s implementation of Codable/Decodable..

4c) The first curious thing about the code above is the mentioning of Encoder/Decoder protocols. (For the sake of brevity, whereever the text below applies to both Encoders and Decoders, I shall simply go with Encoders only.)

There’s a hole the in the documentation.
Apple’s article on encoding and decoding custom types uses a ‘Landmark’ struct as an example, and says Adopting Codable on your own types enables you to serialize them to and from any of the built-in data formats, and any formats provided by custom encoders and decoders. For example, the Landmark structure can be encoded using both the PropertyListEncoder and JSONEncoder classes, even though Landmark itself contains no code to specifically handle property lists or JSON.

I have looked long and hard in the documentation, and I have not been able to find any evidence that NSKeyedArchiver (or its superclass, NSCoder) conforms to the Encoder protocol; yet the code given in this section undoubtedly works, and personally I am convinced that the presence of encodeEncodable means it SHOULD be used as I’m using it here.

The Swift Evolution Proposal SE-0167 confirms that suspicion, but that’s a late update to this post; it’s not a location where I would have looked for information.

Setting a breakpoint reveals something even more intriguing:

_PlistEncoder sounds like a private class, and that’s as far as I can go with this particular puzzle. Unsurprisingly, the Decoder object passed to our init(from decoder:) method is a _PlistDecoder.

As I said above, even though the step of replacing NSCoding with Codable and choosing the appropriate methods on NSKeyedArchiver is a logical step, looking at the documentation only and trying to figure out Codable from that meant that I looked at the two available Encoders and boggled that Apple would create a serialisation solution that did not contain an obvious path for saving to file. (I continue to be boggled by the fact that this is NOT DOCUMENTED and that there is no working code example for it. I mean… No.

throw(Error.OutOfWords)

The existence of a JSONEncoder class as well as a PropertyListEncoder makes more sense when we go back to NSCoding. There is a NSPropertyListSerialization class, which converts data to and from property lists, as well as a NSJSONSerialization class.

Until I looked at NSCoding again for this article, I had not heard of either, but now the parallels are even clearer: it appears that the PropertyListEncoder and JSONEncoder replace these two classes specifically, while NSKeyedArchiver continues to do its thing as before. (Would it have been better to provide a FileEncoder? In my opinion, yes. In the absence of one, mention NSKeyedArchiver, dammit.)

The _PlistEncoder made me worry a little about the integrity of files created with NSKeyedArchiver, though: I will adress this (and other) questions later in this post.

4d) So let’s leave NSKeyedArchiver for a bit, and look at the Encoders/Decoders that have been created specifically to work with the Codable protocol.

The relevant code blocks are:

let archiver = JSONEncoder()
archiver.outputFormatting = .prettyPrinted

do {

let jsonData = try archiver.encode(modernUnicorn)
try jsonData.write(to: saveURL)
} catch {
print(error)

and

do {
let unicornData = try Data.init(contentsOf: loadURL)
let unarchiver = JSONDecoder()
let resurrectedUnicorn = try unarchiver.decode(ModernUnicorn.self, from: unicornData)
} catch {
print(error)

Instead of a JSONEncoder, you can use a PropertyListEncoder (without the prettyPrinted text). This one turns out to be a PropertyListEncoder, as opposed to the _PlistEncoder used by NSKeyedArchiver. Once you change its extension from .unicorn to .plist in the Finder, it becomes a perfectly well-behaved PropertyList.

4e) There are ‘containers’ in the code above. Also, while in NSCoding we need to specify what we decode via a method on NSCoder (decodeObject as? String; decodeBool etc), here the ‘container’ is taking over that responsibility. (There are separate methods for decode and decodeIfPresent, which is a nice way of handling optionals. At least I think so – this article by Ben Scheirman disagrees and suggests encoding all values. [It also has a number of useful JSON examples explaining why you would want to use certain features of Codable and Encoders: if the JSON data structure looks like _this_, you transform it into Swift objects like _that_.])

Containers come in three flavours: keyed, unkeyed, and singleValue; they also can be nested. (If you have a type nested within another, you use nested containers).

A keyed container encodes a dictionary – or a Swift object, which one can conceptualize as a dictionary (where the property names are the keys and the property values the values.) An unkeyed container contains an ordered sequence – in other words, an array of objects, while a single value is, well, just that. So unless I am misunderstanding containers, the compiler automatically nests containers as needed – but if you want to make adjustments, you need to provide the containers yourself.

The article linked above gives as an example

let bottleSizes: [Float]

and replaces the straightforward
try container.encode(bottleSizes, forKey: .bottleSizes)

with

var sizes = container.nestedUnkeyedContainer(
forKey: .bottleSizes)
try bottleSizes.forEach {
try sizes.encode($0.rounded())
}

with a corresponding decoding method:
var bottleSizesArray = try container.nestedUnkeyedContainer(forKey: .bottleSizes)
var bottleSizes: [Float] = [] while (!bottleSizesArray.isAtEnd) {
let size = try bottleSizesArray.decode(Float.self)
bottleSizes.append(size.rounded())
}

In other words, in order to do custom encoding you create a nested container of the appropriate type and ask it to encode your objects.

4f) Rather than duplicating all of the work Ben Scheirman has done, I simply point you to that article again: He also resolves the question of how to encode classes which inherit from others (there is a container.superEncoder involved).

This is somewhat surprising. If you turn the ModernUnicorn into a class, and create a PostmodernUnicorn class inheriting from Modern Unicorn, you would expect

try archiver.encodeEncodable(postmodernUnicorn, forKey: NSKeyedArchiveRootObjectKey)

to just work: after all, ModernUnicorn conforms to Codable and can easily be encoded.

PostmodernUnicorn, on the other hand, fails with Thread 1: EXC_BAD_ACCESS (code=1, address=0x10) which would have sent me into a complete and utter rabbit hole of despair had I encountered this in the process of serialising an app: which bit of the code did I get wrong? (Answer: none, this is the process that works perfectly fine with ModernUnicorn) If I hadn’t encountered the warning first, it would not have occurred to me that Codable does not support inheritance, because inheritance was the foundation of Objective-C programming, and still plays a big role in Swift. [*]

[*] Objective-C had one [well, functionally had one] root base class: NSObject. In Swift, you can have as many as you like. In Objective-C, to model subtle differences between objects, you’d create a class and subclass it; in Swift, you can use protocol composition. Both have extensions/categories; Swift uses them a lot more. Swift has composition baked in conceptually. There’s still an awful lot of inheritance going on.

5) Let’s talk about enums for a moment. This is a *wonderful* moment, since previously you could not encode enums. It turns out that enums are trivial to encode if they are of type String or Int (instead of you encoding a string for an enum value and constructing an enum value from a string, the compiler now does this for you).

If your enum contains an associated value, it’s not quite as easy, but the principle is straightforward enough:

You will need the verbosity of VerboseUnicorn (point 3 above): a CodingKeys enum, and both encode(encoder:) and init(decoder:); and I’ve added an error enum as well. Be aware that you cannot simply copy and paste this code: both encoder and decoder have too many methods, and you need to pick the right one (String.Type, Encodable.protocol) etc. (In Xcode 9.2, the compiler complained otherwise about ambiguity, so it’s safer to type your method.)

You basically tell the encoder what to encode for each case of the CodingKeys, and vice versa.

enum RainbowCreator: Codable {

case unicorn(ModernUnicorn)
case kitten(Kitten)

private enum CodingKeys: String, CodingKey{
case unicorn
case kitten
}

private enum RainbowCreatorError: Error{
case decoding
}

func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)

switch self {
case .unicorn(let unicorn):
try container.encode(unicorn, forKey: .unicorn)
case .kitten(let kitten):
try container.encode(kitten, forKey: .kitten)
}

}

init(from decoder: Decoder) throws {
let values = try decoder.container(keyedBy: CodingKeys.self)
if let unicornValue = try? values.decode(ModernUnicorn.self, forKey: .unicorn) {

self = .unicorn(unicornValue)
return
}
if let kittenValue = try? values.decode(Kitten.self, forKey: .kitten){
self = .kitten(kittenValue)
return
}
throw RainbowCreatorError.decoding
}

}