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:
- The book is a package with a specific folder layout of chapters and pages.
- The left-hand side is a stateless playground with markdown and code.
- 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.
- The playground view and live view can communicate via a simple asynchronous inter-process communication mechanism.
- 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:
- Write the code in Xcode (to get autocomplete, docs, etc)
- Build it there too
- Run it in a host app where I could test the LiveViews in the simulator
- 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.