Category Archives: Swift Playground Books

Playing a Book

I’ve been thinking a lot about what books are for. Specifically, non-fiction books, and more specifically programming books. I’ve finally figured out how to describe what I’ve been thinking: You don’t read a programming book, you play one.

I mean play, like playing a game. In a game, you progress through levels by learning and applying skills. At the end of the level, you play against a boss that you have to beat to progress.

In books, you progress through chapters. But, there is nothing that stops you from just reading and reading and reading and well, not learning or applying anything. At the end of a chapter, you can just turn the page and keep going.

Over on App-o-Mat, an iOS content site I maintain, I’ve been working off and on a companion to the The Swift Programming Language book by Apple. I started the companion on Dev.to with a short section on how to read the book, where I said you should it read it side-by-side with an Xcode Playground page open. That you should not copy any code into it, but type code as you learn it. Get used to typing code.

Then, for each chapter, I offer some simple exercises that let you know that you understood the chapter.

I now realize that I was turning chapters into levels with bosses, which make The Swift Programming Language a book you can play.

iOSDevUK Lightning Talk about Swift Playground Books

Links from the talk

  1. Playground Book package format
  2. WWDC 2016 talk about Swift Playgrounds
  3. My fix of Talking to the Live View
  4. Ash Furrow’s playgroundbook command-line tool
  5. My PlaygroundSupportMock framework for building an app from a book
  6. My pgbookc script for turning a Contents folder in a host app into one that you run as a book
  7. My ShapeSearch playground book and host app built using those tools

Read my previous post on authoring a Swift Playground Book for more information.

Authoring an iOS Swift Playground Book

I expect at some point Apple will have some kind of Playground Book authoring solution, but until then, I’ve hacked together something basic that I am ready to share.

Take a look at my previous post if you’re getting started with playground books. The important things to know are:

  1. The book is a package with a specific folder layout of chapters and pages.
  2. The left-hand side is a stateless playground with markdown and code.
  3. The right-hand side is a stateful live view that can host a View Controller and do pretty much anything you could do in an app.
  4. The playground view and live view can communicate via a simple asynchronous inter-process communication mechanism.
  5. The book is delivered as Swift source files, assets, and plist config files.

As I mentioned in the last post, Ash Furrow has a way to generate this format from a .yaml description and playground files. Even if you don’t ultimately use it as your book source, it’s a good way to generate your initial package structure. The same project also has a linter, which you should use no matter how you author playground books.

The drawback of trying to write an entire book this way is that some of the code lives in the .yaml file and is hard to write and check.

I wanted a way to:

  1. Write the code in Xcode (to get autocomplete, docs, etc)
  2. Build it there too
  3. Run it in a host app where I could test the LiveViews in the simulator
  4. Unit-test the playground and LiveView code

I started by putting a book’s Contents folder into a skeleton app and loading the first page’s LiveView as my rootViewController. The first problem is that on the iPad, there’s a framework called PlaygroundSupport with support for Swift Playground features like the messaging between the playground and LiveView. This framework is not currently available in Xcode.

To make it buildable in Xcode, I made PlaygroundSupportMock. This is a work in progress, and I will add more support of PlaygroundSupport as I need it. You can add it to a skeleton app via Carthage.

The second problem is that the format requires each page folder to have a Contents.swift and an optional LiveView.swift. But, apps cannot have two files with the same name in the same module.  To get around that, I wrote a script called pgbookc to copy the Contents folder from the host app and rename any Contents-*.swift or LiveView-*swift files (removing the -* suffix).

Finally, there are several places in the book where code that would work in the book could not work in an app (and vice versa). So, I added a feature to pgbookc to look for special comments in the Swift files that help it to alter it to work as a book.  For example, here is some typical code you might find in a book (to send a PlaygroundValue dictionary to the LiveView and call it from the playground itself)

func hasAttribute(shape: Shape, attribute: ShapeAttribute) -> Bool {
    let attributes: Set = shape.attributes
    return attributes.contains(attribute)
}

hasAttribute(shape: cloud, attribute: .IsGray)

The problem is the last line, which must be at the top-level in a playground (but cannot work in an app).  So, pgbookc will look for any line that ends with

// REMOVE LINE

and removes that entire line. This lets you write:

func Contents0102() -> Bool { return // REMOVE LINE
hasAttribute(shape: cloud, attribute: .IsGray)
} // REMOVE LINE

The first and last line will be stripped from the book, but it’s there for the app build. It’s also there for tests, which lets me write:

func testContents0102() {
    XCTAssert(Contents0102())
}

To make sure any playground code in a Contents.swift file works.

I have an (almost done) Playground Book that I am writing using this technique. It’s called Shape Search and has the reader build a simple guessing game that teaches how to do a binary search.

Swift Playground Books: 2-Sep-2016

I imagine a lot of the information here is going to go out of date fast, but if you are looking at playground books today, here is where to start.

  1. The WWDC 2016 talk, Introducing Swift Playgrounds, has a lot of technical detail about the .playgroundbook format and how the LiveView proxying works.
  2. The demo for that talk is available on Apple’s dev site, but it’s out of date. I’ve been updating it for each iOS 10 Beta (to track Swift 3). Go to my GitHub to get the fixed Talking to the Live View sample.
  3. The documentation for the .playgroundbook format can be found on the Apple Developer site.
  4. Erica Sadun, who has written the book on Xcode playgrounds did some early investigations of iOS Swift Playgrounds. You might want to read them — here is Part I, Part II, Part III, Part IV,  and Part V.
  5. Ash Furrow made a playground book linter and authoring tool (source). You can use the linter on any .playgroundbook (however you make it), and the authoring tool allows you to specify the parts of the book in a .yaml file, and it puts each piece in the correct file and folder for you in the .playgroundbook package.