I got hooked onto trying to make computers do what I told them a very long time ago and have never stopped loving it. I’m a keen evangelist for developing native Mac apps. When not at my computer, I love coffee, puzzles, reading and cooking — the day hasn’t started until the first cup of coffee is drunk and the crossword is done! — Sarah

I’m a fan of words and the things you can do with them, and I’ve spent a decade floating between different forms of writing — academic, fiction, technical. I hope that in this book I’ve succeeded at easing the passage of ideas between Sarah’s brain and your own, and I ask only that you blame me for any typos, stray capitals, Australianisms, and unoxfordenised commas that have made it into the final manuscript. — Peter

To Tim who is endlessly supportive, even when listening to me complain about all my bugs.

To follow along with this book, you’ll need the following:

The source code for this book can be cloned or downloaded from the GitHub repository:

Click the link to open it in your browser. You’ll see a big green Code button. Click on that and on Download ZIP. This puts all the code files in your Downloads folder.

If you prefer a direct download without source control, use this link: https://github.com/trozware/mos_book_code/releases/latest and download Source code (zip).

Depending on your browser settings, you may need to double-click the ZIP file to expand it. That gives you a folder containing one sub-folder for each chapter. The text of each chapter tells you when you need to use any of these files or folders, but every chapter that involves coding has a final folder showing the end result of working through that chapter.

The chapters in each section are designed to take you from start to finish building a particular kind of app. While the book is fun from the first page to the last, if one section especially piques your interest, you’re free to dive right in there.

When you get to the code blocks, if the code is unfamiliar to you, then I strongly recommend that you type it in for yourself, rather than copy and paste it. Xcode’s autosuggestions will help you type, and having to get every detail correct will embed the new knowledge in your brain in a way that reading it can’t.

If you are using copy and paste for any of the code blocks, then go to Xcode’s Settings and in Text Editing → Indentation, turn on Re-Indent on paste. This will solve a lot of issues with the format of the text in the book differing from Xcode’s format.

This book is available as HTML, PDF or ePub. I recommend reading this book from the HTML version. It has good light and dark variations and the most accurate formatting. Also, the code blocks have a COPY button for when you want it, and there are no issues with pagination. My next favorite is PDF — use the light or dark version to suit your preference. My least favorite option is the ePub, as its display depends greatly on your ePub reader. Apple’s Books app makes copying any code sections particularly problematic as it adds copyright information to the clipboard every time.

If you find any errors or typos, please report them to me at [email protected]. For problems with the code, please open an issue at https://github.com/trozware/mos_book_code/issues.

This book is split into five sections:

You’ll use the API from ZenQuotes.io. Go to today.zenquotes.io in your browser and look around the page. At the top, you’ll see an interesting historical event that happened on this day of the year, and you can scroll down to see more:

Keep scrolling until you get to the Quick Start heading. Underneath that, the Fetch Historical Events subsection gives you the format for the URL to access the data. Scroll all the way to the bottom and check the Usage Limits too. When testing, it’s easy to hit this limit, so one of your first tasks is to download a sample set of data to work with.

Under the Quick Start heading, follow the Read the full documentation link to get more information on the structure of the JSON returned by the API call. You’ll get to explore that in detail over the rest of this chapter.

If you haven’t already downloaded the supporting materials, follow the instructions in the Where to download the materials for this book section of the preface.

Open the playground from the starter folder for this chapter. It’s a macOS playground set up with some functions to get you going. The most important one is getDataForDay(month:day:), which takes in a numeric month and day, assembles them into a URLRequest and then uses URLSession to download the JSON from that URL.

If the data returned can be converted into a String, the function will save it to a file. But where should you save it? Unlike iOS, macOS gives you full access to the file system. The app sandbox may restrict this, as you’ll learn in later chapters, but in a playground, you can access everything. Since this is data you’re downloading, saving it to the Downloads folder makes the most sense, so now you need to work out the file path for the Downloads folder.

Now that you have the data saved and formatted, you can start using it instead of calling the API server every time. This is faster and avoids hitting the usage limit.

To begin, comment out the entire Task section but don’t delete it in case you need to re-fetch the data later. Next, add this code to access the saved data instead:

Finally, run the playground again and you’ll see a number showing the amount of data in the sample file:

I deliberately chose February 29 for the sample day to minimize the amount of data. Presumably only a quarter of the usual number of interesting events happened on February 29th. :-) You may get a different number as the site adds and deletes events, but any number over zero shows that you have read some data from the sample file.

To make it easier to examine the structure of the JSON data returned, turn on code folding. If you’re using Xcode, go to the menu bar and choose Xcode → Settings…​ → Text Editing → Display, then select the checkbox labeled Code folding ribbon:

Now you’ll be able to click in the ribbon beside the line numbers to collapse and expand the data nodes. By collapsing nearly all the nodes, you can see that the root structure of the layout contains four elements. data and date are the ones you need here. No way of confusing those two! :-) You can ignore the info and updated elements:

Inside data, there are three nodes — one for each of the three different types of event: Births, Deaths, and Events. The data inside each of them has the same structure, so after expanding Births to show the first one, you’ll see this:

The three top level elements are html, links and text. If this was for display in a web page, html would be important, but for an app, text is much more useful. Notice how it includes HTML entities and starts with the year.

The links section is oddly structured with the keys being numbers inside strings. Each link has three elements with "0" being the full HTML link, "1" containing the URL, and "2" holding the text for the link.

Now you’ve explored the JSON and know what you’re getting from the API server, it’s time to start decoding it. The overall data model for this JSON will be a struct called Day since it contains the information for a specific day. Day will have data and date properties. date is a string, so start with that.

First, add this code to the playground:

This establishes Day as a struct that conforms to the Decodable protocol. Since this data will never be re-encoded, there’s no need to conform to Codable which is a type alias for Decodable & Encodable.

To test this, replace print(data.count) with this:

Then run the playground again and you’ll see "February_29" printed in the console.

Decoding the data element isn’t so straightforward as there are different types of data inside. It’s time to think about the lower level data models.

You can decode each entry in the "Births", "Deaths", and "Events" elements into an Event data model. Event needs two properties: text and links — you can ignore html. To set this up, add a new struct to the playground:

For now, links is an ugly dictionary containing more dictionaries, but this is enough to get it decoding.

Next, insert the new data property into Day:

And lastly, add a second debug print after print(day.date):

Run the playground again and you’ll see the date and a number showing how many notable births fell on that day:

The final piece in the puzzle is the links, so create a new struct called EventLink to handle them:

This is the important data for each link, but the incoming JSON isn’t structured like this. To process the data as it comes in, Event needs to do some more work.

Right now, your Event struct stores its links in a dictionary, which decodes them but doesn’t make the links easy for the app to use. By adding a custom init(from:) to Event, you can process the incoming JSON into a more usable format.

Replace Event with this version:

It was so clean and simple a moment ago and now look at it! Let’s step through this code and see what I did:

To test that this is decoding the data correctly, add a third debug print statement under the other two. It force-unwraps the array of Births, which is a bad idea in production but is fine in a testing playground:

Now run the playground. This time, it’ll take a while to finish. As Event.init(from:) loops, you’ll be able to see the results on the right flickering. Playgrounds aren’t great at doing multiple loops, but this is very fast inside an app.

The link output isn’t wonderfully readable, but you can see they’re all there, each with a title and a URL:

Now that you’re decoding the JSON and have created the basic data structure, it’s time to consider how the app will use this data and what you can add to make this easier.

Looking at Day first, it would be convenient to have a more direct way of accessing the various categories of events instead of using an optional like day.data["Births"] each time.

There are three types of events, so to avoid using magic strings as dictionary keys, start by adding this enum which describes them:

Conventionally, the cases in an enum start with a lowercase letter, but the raw string values are the title case strings that appear in the JSON, so they’ll work as keys to the data dictionary.

With the enum in place, add these computed properties to Day:

These properties use the raw value to return an array of the relevant events or an empty array.

Now you can change the inelegant debug print statements so they use no optionals and no force unwrapping:

The second feature that would be useful in Day is a nicer way to show the date. Right now, there’s an underscore between the month and the day. You could use a custom init(from:) to change the way you decode it, but you’re going to use another computed property instead. Add this to Day:

To test this, change the first of the debug print statements to:

Run the playground again to see updated date string:

Not much different to see here except for the formatted date, but you accessed the information much more easily.

Take a moment to think about how your app might display the information in Day. displayDate is a String and all ready for use. Then you have the arrays containing Events and EventLinks, which the views in your app will loop through in some manner. When looping through arrays of data in SwiftUI, it’s important that each element has a unique identifier. This allows the SwiftUI engine to track which elements have changed, moved or disappeared, so it can update the display as efficiently as possible.

The best way to do this is to make the model structs conform to Identifiable. This protocol requires the conforming type to contain a property called id, which can be anything, but is usually a string, a number or a unique ID. Some data might arrive with IDs already. In this case there’s nothing obviously unique, so you’ll add a UUID to each Event and EventLink.

Starting with EventLink, edit the struct declaration to include Identifiable and add an id property:

Run the playground again and you’ll see this error in the console:

This is in the Event struct’s init(from:) method where it creates each EventLink. Replace the processedLinks.append(EventLink(title: title, url: url)) line with:

For Event, you want to do something similar - conform to Identifiable and add an id property. In this case, the declaration initializes the UUID itself. Replace struct Event: Decodable { with:

If you had used this technique for EventLink, you’d have seen a warning about an immutable property which won’t be decoded. This isn’t a problem with Event, because you’ve set up the CodingKeys, which tell the decoder which properties to use and which to ignore.

Now that you’re prepared for looping through the events and links, it’s time to look at the text for the events. In your debugging print statements, replace the line printing the links with this one and run the playground again:

In the console, you’ll see "1468 – Pope Paul III (d. 1549)" or something similar. You can see the text string starts with the year and then uses the HTML entity for an en dash to separate this from the information. For display purposes, it seems like it’d be useful to separate these two parts into distinct properties.

First, add a year property to Event. You may be tempted to convert the year into an Int, but remember that some events happened a long time ago and may include "BC" or "BCE", so the years need to remain as strings:

Replace the line in init(from:) that sets text with this:

Let’s step through this code:

Time to add yet another debug print statement:

Run the playground again and you’ll see something like this:

So far, you’ve created a series of data structs: Day, Event and EventLink. Now, it’s time to pull them all together into a class, which is the primary data model in your app.

Add this definition to the playground:

To test this, go to the top of the playground and add these lines immediately after the import line:

This creates an AppState object, sets the month and day and then adds a function for testing the result. These definitions need to be at the top because playgrounds run from top to bottom and these have to be set up before anything tries to use them.

Scroll back down to where you read the sample data file and printed some debugging information. Replace all of the print statements with the following:

Run the playground and you’ll see a result like this in the console:

As a final check, how about re-enabling the actual download and making sure your code can process live data correctly? Right now, the download saves the data to a text file, so you need to change the download function to make it decode this data into a Day and return it.

First, find getDataForDay(month:day:) and replace its signature line with this one which sets it to return a Day:

Next, below where you save the data to a file, add this chunk, which attempts to decode the downloaded data into a Day and throws an error if it can’t:

Finally, comment out the entire code block that begins if let data = readSampleData() { and add the following after it:

This is similar to the Task you used to get the sample data, but this version waits for the decoded Day to come back, adds it to appState's days, and calls the test function.

If there’s a download error or a decoding error, the catch block prints the error.

Click the Execute Playground button again. You’ll see a message reporting the saved file path, and then you’ll see the debug report:

For fun, try changing monthNum and dayNum at the top of the playground and running it again to fetch some different data. Add more print statements to testData() if you want to see what you’ve got.

This chapter may have seemed like hard work when you wanted to get started building a real macOS app, but in the next chapter, you’ll see how this preliminary work means that the app can start taking shape quickly.