Active Filters: Playgrounds

One of the most useful parts of Xcode Playgrounds is the way they allow us to visualize our code. We can click the Quick Look button, or insert a preview directly into our code with the Show Result button in the Results sidebar:

We can add visual representations to the assistant timeline using XCPlayground's captureValue function (Bite #136).

This can be incredibly handy for spotting problems quickly:

Tons of system types are supported like CGPath, NSURLs, and even many of SpriteKit's classes. These are actually the same representations that can be seen if we Quick Look something while debugging in Xcode.

We can add these capabilities to our own custom types (for both debugging and Playgrounds) by adding a function like this to them, returning a supported type:

func debugQuickLookObject() -> AnyObject? { return name }

This is great, but only works on types that inherit from NSObject and won't work for things like Swift structs. Also, even though we're adding this to our own type, we'll still need to return one of the built-in, Quick Look-able types supported by Xcode.

For more flexibility, let's look at XCPlayground's XCPlaygroundLiveViewable protocol.

This will let us visualize our own types by returning a view or view controller that will be shown in the assistant timeline when we capture a value:

extension Person : XCPlaygroundLiveViewable {
  func playgroundLiveViewRepresentation() -> XCPlaygroundLiveViewRepresentation {
    let vc = PersonLiveViewableViewController(person: self)
    return .ViewController(vc)

Now, we can set our current page's liveView to a instance of Person directly, and we'll see our custom view controller appear in the assistant timeline. Neat!

XCPlaygroundPage.currentPage.liveView = Person()
XCPlaygroundPage.currentPage.needsIndefiniteExecution = true

We're continuing our look at Xcode Playgrounds today with CocoaPods. Let's see what it takes to import a CocoaPod into a Playground.

We'll begin by creating a new Xcode Project. Next, we'll head into our project's directory and run pod init to generate our Podfile. We'll open it up and configure it just as we usually would:

platform :ios, '9.0'
link_with 'Spaceships'

pod 'Alamofire'

Then we'll run pod install to generate the Workspace file for our project and install our pods. We're almost done, next we need create a new Playground and add it to our project.

Finally, we need to add our Playground to our Podfile's link_with directive (only its name, not the .playground extension):

link_with 'Spaceships', 'scratch-pad'

We'll run pod install one more time and we're done. We can now import the pod we installed into our Playground and try it out. Neat!

Xcode Playgrounds are great for trying out code quickly, or testing out a new API or framework. They can also be a wonderful form of interactive documentation.

Today we'll look at a few ways we can write our own interactive docs using rich comments in Xcode Playgrounds.

One of the primary ways we'll turn our Playgrounds into documentation is through rich comments.

Playgrounds have two "markup" modes: raw vs. rendered. As their names suggest, each mode specifies whether Xcode should "render" rich comments in our Playground, or make them editable.

We'll begin by creating a new Playground. Then we'll select Editor > Show Rendered Markup to switch modes.

Right away, we can see the top comment changes from:

//: Playground - noun: a place where people can play

To this:

We can write our own rich comments by adding a : symbol after the // in any comment to convert it to a rich one. Neat!

Rich comments' Markup syntax is heavily inspired by Markdown. (It's basically just Markdown).

Apple has a syntax guide, but here's the idea:

//: We can write regular text, **bold** text or *italic* text.
//: ## Headers

We can include links in our rich comments:

//: A great [link](

We can allow readers to navigate pages with some special links:

//: [Next](@next) or [Previous](@previous)

Or link to specific pages (names will need to be URL encoded):

//: [View Models](View%20Models)

We can even include images in our rich comments. We just need to first add them to our Playground's Resources group, then use Markdown's normal image syntax:

//: ![](playgrounds-rock.gif)


#136: XCPlayground Basics 🎪


Xcode Playgrounds arrived in Xcode 6. They're a great way to try out some code quickly, or to learn about an API or library through interactive documentation.

Playgrounds are unbelievably useful out-of-the-box, but today we'll look at a framework called XCPlayground that makes them even better.

XCPlayground ships with Xcode. We can import it in our Playgrounds to enable all sorts of interesting functionality.

We'll begin by creating a new Playground. We can do this by selecting File > New > Playground… from Xcode's menu (or ⌥⇧⌘N). Then we'll import XCPlayground:

import XCPlayground

Let's start with one of the most common reasons for importing XCPlayground, indefinite execution. By default Playgrounds execute the code in each page, from top-to-bottom, then they stop executing. We can change this behavior like so:

XCPlaygroundPage.currentPage.needsIndefiniteExecution = true

This will allow any asynchronous code we have in our Playground to continue running indefinitely.

Once our code is done, we can call:


Another great use for Playgrounds is prototyping views. We'll need to enable needsIndefiniteExecution first, then:

XCPlaygroundPage.currentPage.liveView = containerView

We set the current page's liveView property to any UIView or NSView and it will appear visually in the assistant editor.

If the assistant editor isn't already visible, we can open it by selecting View > Assistant Editor > Show Assistant Editor from Xcode's menu (or ⌥⌘↩︎).

Similarly, we can add a value to the assistant editor (including a corresponding label so know what's what) like this:

XCPlaygroundPage.currentPage.captureValue(containerWidth, withIdentifier: "Width")

We'll be looking at more neat features of Playgrounds soon. Please send your favorite Playground tips to!