Last time, we looked at Context-free Grammars, Recursive Descent Parsing and Operator Precedence Parsing. Let's complete the missing pieces in our trivial language, Kaleidoscope.

Here's some grammar that describes declaring a function:

Function -> Prototype Expression  
Prototype -> Define Identifier ( Arguments )  
Arguments -> Arguments, Identifier | Identifier | ε  

Functions are declared with a Prototype followed by a single Expression. The Prototype consists of the keyword def, which is represented by the Define symbol, followed by an Identifier and a pair of parenthesis. Any arguments are included comma-separated within the parenthesis. In the grammar above, we denote the empty string "" with epsilon, ε.

Similarly we can write production rules for calling a function:

PrimaryExpression -> Call | Identifier | Number | ( Expression )  
Call -> Identifier ( Parameters )  
Parameters -> Parameters, Expression | Expression | ε  

To call a function, we first have an Identifier that represents the name of the function, followed by any parameters comma-separated within the parenthesis.

Let's look at how we can create the corresponding nodes in our AST:

struct PrototypeNode: CustomStringConvertible {  
    let name: String
    let argumentNames: [String]
    var description: String {
        return "PrototypeNode(name: \(name), argumentNames: \(argumentNames))"
    }
}

struct FunctionNode: CustomStringConvertible {  
    let prototype: PrototypeNode?
    let body: ExprNode
    var description: String {
        return "FunctionNode(prototype: \(prototype), body: \(body))"
    }
}

We'll explain why the prototype property is optional later. Similarly, here's how function calls are represented:

struct CallNode: ExprNode {  
    let name: String
    let arguments: [ExprNode]
    var description: String {
        return "CallNode(name: \(name), arguments: \(arguments))"
    }
}

Notice the symmetry between function declarations and function calls. This would hint to us that we should write code that share logic in some way. In particular, we can factor the logic that parses a comma-separated list into a method that takes as input the logic for generating the list elements (specifically ExprNode for parameters and String for argument names.)

Here's the parsing logic for identifiers and function calls:

func readIdentifier() throws -> String {  
    guard case let Token.Identifier(name) = popCurrentToken() else {
        throw ParseError.ExpectedIdentifier
    }
    return name
}

func parseIdentifierOrFunctionCall() throws -> ExprNode {  
    let name = try readIdentifier()

    guard tokensAvailable else {
        return VariableNode(name: name)            
    }

    guard case Token.ParensOpen = peekCurrentToken() else {
        return VariableNode(name: name)
    }

    let arguments = try parseParensList(parseExpression)
    return CallNode(name: name, arguments: arguments)
}

If there is a ( symbol after the Identifier, we assume it to be a function call. We also assume the method func parseParensList will parse a comma-separated list of something. In this case, we have it return parameters which are just Expressions via the func parseExpression() method defined earlier.

Next, let's take a look at parsing function declarations:

enum ParseError: ErrorType {  
    ...
    case ExpectedFunctionDeclaration
    case ExpectedFunctionName
}

func parsePrototype() throws -> PrototypeNode {  
    guard case let Token.Identifier(name) = popCurrentToken() else {
        throw ParseError.ExpectedFunctionName
    }

    let argumentNames = try parseParensList(readIdentifier)
    return PrototypeNode(name: name, argumentNames: argumentNames)
}

func parseDefinition() throws -> FunctionNode {  
    guard case Token.Define = popCurrentToken() else {
        throw ParseError.ExpectedFunctionDeclaration
    }

    let prototype = try parsePrototype()
    let body = try parseExpression()
    return FunctionNode(prototype: prototype, body: body)
}

This time, our customisation to func parseParensList() is func readIdentifier() which returns the String of the name of an Identifier. The parsing of the function definition is rather trivial.

Now, we're ready to talk about how we can actually parse the list of ExprNodes or Strings in each case. We allow customisation with 2 swift features:

1) We take a closure as input to perform the actual reading
2) We use a generic method that allows us to have the correct return type depending on the input closure

enum ParseError: ErrorType {  
    ...
    case ExpectedCommaSeparatedList
}

func parseParensList<T>(@noescape read: () throws -> T) throws -> [T] {  
    guard case Token.ParensOpen = popCurrentToken() else {
        throw ParseError.ExpectedCharacter("(")
    }

    if case Token.ParensClose = peekCurrentToken() {
        return []
    }

    var list = [T]()
    while true {
        let element = try read()
        list.append(element)

        if case Token.ParensClose = peekCurrentToken() {
            break
        }

        guard case Token.Comma = popCurrentToken() else {
            throw ParseError.ExpectedCommaSeparatedList
        }
    }

    guard case Token.ParensClose = popCurrentToken() else {
        throw ParseError.ExpectedCharacter(")")
    }

    return list
}

We're using the @noescape attribute here to tell the Swift compiler that this closure will not be used outside of this method and allows us to ignore any reference semantics for capturing variables.

We begin by looking for ( followed by ) which essentially means we have an empty list. If we don't find the closing parenthesis, we should read the element and add it to our list. Each element should be followed by the closing parenthesis or a comma if there are more elements after. Finally, we discard the closing ) and return the list.

Next, we also need to update our method func parsePrimary() to understand function calls:

func parsePrimary() throws -> ExprNode {  
    switch (peekCurrentToken()) {
    case .Identifier:
        return try parseIdentifierOrFunctionCall()
    case .Number:
        return try parseNumber()
    case .ParensOpen:
        return try parseParens()
    default:
        throw ParseError.ExpectedExpression
    }
}

Now, we are ready to finish our Parser class. We're going to simplify things by representing top-level expressions as a FunctionNode without a prototype (we made this optional earlier.)

func parseTopLevelExpr() throws -> FunctionNode {  
    let body = try parseExpression()
    return FunctionNode(prototype: nil, body: body)
}

func parse() throws -> [Any] {  
    index = 0

    var nodes = [Any]()
    while index < tokens.count {
        switch peekCurrentToken() {
        case .Define:
            let node = try parseDefinition()
            nodes.append(node)
        default:
            let expr = try parseTopLevelExpr()
            nodes.append(expr)
        }
    }

    return nodes
}

Now we can parse a series of function definitions or expressions:

let parser = Parser(tokens: tokens)  
do {  
    print(try parser.parse())
}
catch {  
    print(error)
}

If we pass in the following input:

def sum(x, y) x+y  
sum(4, 3)  

We get a nice list of FunctionNodes:

[
FunctionNode(  
    prototype: Optional(PrototypeNode(
        name: sum, 
        argumentNames: ["x", "y"])), 
    body: BinaryOpNode(
        +, 
        lhs: VariableNode(x), 
        rhs: VariableNode(y))), 
FunctionNode(  
    prototype: nil, 
    body: CallNode(
        name: sum, 
        argument: [NumberNode(4.0), NumberNode(3.0)]))
]

Coming up next, we'll talk about how we can use LLVM to run this program!

In this post, we'll look at how to build an Abstract Syntax Tree from a series of tokens.

Firstly, we'll look at how to construct a grammar that describes what is allowed in the language. One of the useful tools we have is the Context-free Grammar. This allows us to describe the language as a set of rules called productions. In fact, the Swift Reference describes the language in this form!

Here's an example:

Expression -> Identifier | Number  

Production rules allow us to replace symbols on the left (which by definition are non-terminal) by a sequences of symbols of the right (which may or may not be terminal symbols.) This particular rule says that an Expression symbol can be replaced by either an Identifier symbol or a Number symbol. For our purposes, these symbols are equivalent to tokens returned from our lexer.

Of course, production rules in practice are never so simple. Recall the following expression from the previous post:

x + y * 2 + (4 + 5) / 3  

There's no way we can describe this using the above production rule. Let's try a slightly more exhaustive version:

Expression -> Identifier | Number | ( Expression )  

This version of the production rule lets us deal with parenthesised expressions, but we're still missing operators.

Expression ->  
  PrimaryExpression Operator Expression | PrimaryExpression
PrimaryExpression -> Identifier | Number | ( Expression )  

Another feature of production rules in Context-free Grammars is that they can be recursive. This allows us to describe more complex language features (especially arithmetic) which we are familiar with in common programming languages.

We now have a production rule which describes a PrimaryExpression which can be either an Identifier, a Number or a parenthesised Expression. This is in turn used to describe Expression which may or may not include Operators with PrimaryExpressions.

This is probably enough theory. Let's take a look at how we can implement this parser in code.

class Parser {  
    let tokens: [Token]
    var index = 0

    init(tokens: [Token]) {
        self.tokens = tokens
    }

    var tokensAvailable: Bool {
        return index < tokens.count
    }

    func peekCurrentToken() -> Token {
        return tokens[index]
    }

    func popCurrentToken() -> Token {
        return tokens[index++]
    }
}

We initialise the parser with a list of Tokens. This essentially sets up the initial state. Next, we have a couple of convenient helper methods which allow us to inspect tokens. The method func peekCurrentToken() returns the next available token. This is commonly known as look-ahead in parser terminology.

The method func popCurrentToken() also returns the current token but moves the index pointer one over, "consuming" the token. As we build our AST, we will generate tree nodes and consume the corresponding tokens as we go.

Let's define our nodes:

protocol ExprNode: CustomStringConvertible {  
}

Firstly, we have a base protocol ExprNode which allows us to describe nodes in Expressions. For convenience, we also inherit CustomStringConvertible so we can have nice print()s when debugging.

struct NumberNode: ExprNode {  
    let value: Float
    var description: String {
        return "NumberNode(\(value))"
    }
}

struct VariableNode: ExprNode {  
    let name: String
    var description: String {
        return "VariableNode(\(name))"
    }
}

For our first 2 nodes, we have NumberNode and VariableNode. As you might expect, NumberNode corresponds with the Token.Number and VariableNode with Token.Identifier. We could have simply used our Token enumeration as nodes in our tree but you will soon see that tree nodes also include more context than there is in our lexical tokens.

struct BinaryOpNode: ExprNode {  
    let op: String
    let lhs: ExprNode
    let rhs: ExprNode
    var description: String {
        return "BinaryOpNode(\(op), lhs: \(lhs), rhs: \(rhs))"
    }
}

The next node, BinaryOpNode, describes the infix operation. It has lhs, rhs and op as properties which correspond to the left-hand side, right-hand side and operator in a binary operation. Now it's evident why we created the ExprNode protocol. Either sides of the operation can contain NumberNode, VariableNode or BinaryOpNode (or future nodes we might introduce.)

With this, we can describe the complex expression we had at the beginning (repeated below):

x + y * 2 + (4 + 5) / 3  

Here's how we parse Token.Number and Token.Identifier:

enum ParseError: ErrorType {  
    case ExpectedNumber
    case ExpectedIdentifier
}

func parseNumber() throws -> ExprNode {  
    guard case let Token.Number(value) = popCurrentToken() else {
        throw ExpectedNumber
    }
    return NumberNode(value: value)
}

func parseIdentifier() throws -> ExprNode {  
    guard case let Token.Identifier(name) = popCurrentToken() else {
        throw ParseError.ExpectedIdentifier
    }
    return VariableNode(name: name)
}

We read the current token (consuming it), check if it's what we expect, and return the corresponding node.

Next, we'll first show the declaration for parsing the Expression symbol because we need to use this recursively (also known as Recursive Descent Parsing.) We'll fill this out later:

func parseExpression() throws -> ExprNode  

Now let's try to parse the parenthesised Expression:

enum ParseError: ErrorType {  
    ...
    case ExpectedCharacter(Character)
}

func parseParens() throws -> ExprNode {  
    guard case Token.ParensOpen = popCurrentToken() else {
        throw ParseError.ExpectedCharacter("(")
    }

    let exp = try parseExpression()

    guard case Token.ParensClose = popCurrentToken() else {
        throw ParseError.ExpectedCharacter(")")
    }

    return exp
}

With this, we have all the ingredients we need to write func parsePrimary():

enum ParseError: ErrorType {  
    ...
    case ExpectedExpression
}

func parsePrimary() throws -> ExprNode {  
    switch (peekCurrentToken()) {
    case .Identifier:
        return try parseIdentifier()
    case .Number:
        return try parseNumber()
    case .ParensOpen:
        return try parseParens()
    default:
        throw ParseError.ExpectedExpression
    }
}

If we create a parse tree for the expression in terms of binary operations naively, you might notice we could potentially create different versions of the tree with any of the operators at the root node. Of course, mathematically not all versions would be deemed correct. We need a way to encode our mathematical rules about which operators act first (also known as the order of operations.)

This can be done with Operator Precedence Parsing, in which we give each operator a precedence (read priority level.)

let operatorPrecedence: [String: Int] = [  
    "+": 20,
    "-": 20,
    "*": 40,
    "/": 40
]

enum ParseError: ErrorType {  
    ...
    case UndefinedOperator(String)
}

func getCurrentTokenPrecedence() throws -> Int {  
    guard tokensAvailable else {
        return -1
    }

    guard case let Token.Other(op) = peekCurrentToken() else {
        return -1
    }

    guard let precedence = operatorPrecedence[op] else {
        throw ParseError.UndefinedOperator(op)
    }

    return precedence
}

Let's look at the code and then explain how it works:

enum ParseError: ErrorType {  
    ...
    case ExpectedOperator
}

func parseBinaryOp(node: ExprNode, exprPrecedence: Int = 0) throws -> ExprNode {  
    var lhs = node
    while true {
        let tokenPrecedence = try getCurrentTokenPrecedence()
        if tokenPrecedence < exprPrecedence {
            return lhs
        }

        guard case let Token.Other(op) = popCurrentToken() else {
            throw ParseError.ExpectedOperator
        }

        var rhs = try parsePrimary()
        let nextPrecedence = try getCurrentTokenPrecedence()

        if tokenPrecedence < nextPrecedence {
            rhs = try parseBinaryOp(rhs, exprPrecedence: tokenPrecedence+1)
        }
        lhs = BinaryOpNode(op: op, lhs: lhs, rhs: rhs)
    }
}

We begin with a node which is potentially the beginning of a binary operation and repeat the following:

• Read the next token;
• If it's not an operator, we're done
• If it has lower precedence than the current one, we're done (it would have been handled earlier in the call stack)
• Consume and read the next PrimaryExpression as rhs
• If the operator after has a higher precedence, recursively make a sub tree starting at rhs at the next precedence level
• Form a sub-tree with the current operator

The intuition behind this is that lower precedence operators tend to appear closer to the root of the tree because higher precedence operators form sub-trees with ever higher precedence operators.

Finally, we can finish func parseExpression() and you will see it's rather trivial:

func parseExpression() throws -> ExprNode {  
    let node = try parsePrimary()
    return try parseBinaryOp(node)
}

Now we can make a call to our parser:

let parser = Parser(tokens: tokens)  
do {  
    print(try parser.parseExpression())
}
catch {  
    print(error)
}

And we should get the following output (with indention added):

BinaryOpNode(  
  +, 
  lhs: BinaryOpNode(
    +, 
    lhs: VariableNode(x), 
    rhs: BinaryOpNode(
      *, 
      lhs: VariableNode(y), 
      rhs: NumberNode(2.0)
      )
    ), 
  rhs: BinaryOpNode(
    /, 
    lhs: BinaryOpNode(
      +, 
      lhs: NumberNode(4.0), 
      rhs: NumberNode(5.0)
      ), 
    rhs: NumberNode(3.0)
    )
  )

Here's a more beautiful version of that tree with ASCII art:

        +
     ___|___
   /         \
  +          (/)
 / \         / \
x   *       +   3  
   / \     / \
  y   2   4   5

Once again here's what we were trying to parse:

x + y * 2 + (4 + 5) / 3  

Because this post is getting rather long, we'll examine other nodes in the AST (such as function calls and declarations) in the next post! You can find all this code on Github. Stay tuned...

1. The notification name is a String type which is subject to typing errors or enforces a design pattern where you would declare constants to avoid this.
2. Consumers of the API are required to unregister when they are no longer interested in notifications.
3. Parameters are passed via a userInfo dictionary and type information is lost in the process.

We can solve problems 1 and 3 easily but simply requiring users to declare a protocol. This gives us a name to refer to this bit of functionality and also allows consumers to define the requirements (read parameters) of the notification.

The delegate design pattern makes uses of protocols but is usually a one-to-one relationship between the delegate and the consumer (instead of enabling action at a distance.) The second problem we can solve by storing the observers weakly via NSHashTable.

Here's how we would use such a solution:

protocol TestProtocol {  
  func hello()
}

We'll declare the protocol that defines the functionality we want to expose.

class TestClass: TestProtocol {  
  let name: String

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

  func hello() {
    print("hello \(name)")
  }
}

Next, we implement the protocol in a class.

let object = TestClass(name: "First")  
let object2 = TestClass(name: "Second")  

Suppose we instantiate several instances of the class.

NotificationManager.sharedManager.add(TestProtocol.self, observer: object)  
NotificationManager.sharedManager.add(TestProtocol.self, observer: object2)  

We'll subscribe to notifications via the func add() method.

NotificationManager.sharedManager.make(TestProtocol.self) { (item) -> Void in  
  item.hello()
}

Here's how we can fire off notifications. We call the methods in the protocol inside of a closure and it gets fired on all observers.

hello First  
hello Second  

The output shows the desired result.

Let's explore how we can build such a solution:

class NotificationManager  
{
  static let sharedManager = NotificationManager()
  var observersMap = [String:NSHashTable]()
}

We start by having a similar way to access a singleton if necessary. Next, we need a way to add observers to our dictionary, observersMap.

func add<T>(type: T.Type, observer: T) {  
  let typeString = "\(T.self)"
  let observers: NSHashTable

  // get the weak set of observers matching this type
  if let set = observersMap[typeString] {
    observers = set
  } else {
    observers = NSHashTable.weakObjectsHashTable()
    observersMap[typeString] = observers
  }

  observers.addObject(observer as? AnyObject)
}

We can do this by writing a generic method. It takes as parameters a type T and an observer conforming to T. Next, we produce a String matching the name of T because the key to a dictionary needs to be Hashable and String conforms to that.

We check to see if we already have a NSHashTable matching that type. If we don't we'll just instantiate one and add it to the dictionary. Finally we add our observer to it. Note that our observer needs to be an object, because the hash table is an Objective-C class.

Now we're ready to write our func make() method. This method makes the observers registered perform a given closure. We've specified the closure to be @noescape. This means it will not out-live the func make() method and we won't have to worry about capturing references.

func make<T>(type: T.Type, @noescape closure: T -> Void) {  
  let typeString = "\(T.self)"
  if let set = observersMap[typeString] {
    for observer in set.allObjects {
      closure(observer as! T)
    }
  }
}

Let me know what you think and if this is a better solution than NSNotificationCenter!

The goal here is not to write the most efficient implementation but how we can leverage features in Swift to make ourselves easily understood.

A compiler can typically be thought of as a series of modular steps including lexical analysis, parsing, semantic analysis, optimisation and code generation.

In the lexical analysis phase, we simply try to break up the input (source code) into the small units called lexemes. These units carry specific meaning which we can categorise into groups of tokens.

Consider the following code snippet:

# Compute the x'th fibonacci number.
def fib(x)  
  if x < 3 then
    1
  else
    fib(x-1)+fib(x-2)

# This expression will compute the 40th number.
fib(40)  

If you've seen any sort of programming language before, you'll immediately recognise the keywords such as def, if, then, and else. In addition, you might also notice fib and x are identifiers. Even though, they are not the same string, we see that they are names for things (namely functions and variables.)

Here's a simpler snippet:

def foo(x, y)  
  x + y * 2 + (4 + 5) / 3

foo(3, 4)  

Our lexer should be able to scan through code and return a list of tokens that describe it. At this stage, it's not necessary to interpret the code in any way. We just want to identify different parts of the source and label them.

Let's jump in and try to determine what tokens we need to describe the language:

enum Token {  
    case Define
    case Identifier(String)
    case Number(Float)
    case ParensOpen
    case ParensClose
    case Comma
    case Other(String)
}

Because each group of lexemes or token has a clear purpose, we can represent them via the enum in Swift. Not all tokens are equal, however. Certain structures like Identifiers and Numbers, also carry additional information.

Next, we'll try to write a program to turn the above snippet into the following output:

[
.Define,
.Identifier("foo"),
.ParensOpen,
.Identifier("x"),
.Comma,
.Identifier("y"),
.ParensClose,
.Identifier("x"),
.Other("+"),
.Identifier("y"),
.Other("*"),
.Number(2.0),
.Other("+"),
.ParensOpen,
.Number(4.0),
.Other("+"),
.Number(5.0),
.ParensClose,
.Other("/"),
.Number(3.0),
.Identifier("foo"),
.ParensOpen,
.Number(3.0),
.Comma,
.Number(4.0),
.ParensClose,
]

One way we can try to do this is via regular expressions. Each token can be recognised by characters it is made out of. For instance, the Define token is always the characters def in that order. Identifiers, however, follow a rule such as 1) any sequence of alphanumeric characters 2) not beginning with a digit.

For each token, we'll write a regular expression capable of matching its corresponding lexeme. Next, we need to generate the enum that matches the token. We can put this all together rather concisely as an array of tuples.

The first parameter in the tuple represents the regular expression we want to match at the beginning of the context and the second parameter is a closure that will generate the relevant token enumeration.

typealias TokenGenerator = (String) -> Token?  
let tokenList: [(String, TokenGenerator)] = [  
    ("[ \t\n]", { _ in nil }),
    ("[a-zA-Z][a-zA-Z0-9]*", { $0 == "def" ? .Define : .Identifier($0) }),
    ("[0-9.]+", { (r: String) in .Number((r as NSString).floatValue) }),
    ("\\(", { _ in .ParensOpen }),
    ("\\)", { _ in .ParensClose }),
    (",", { _ in .Comma }),
]

The first rule captures whitespace which can be spaces, \t tabs or \n line breaks.

Finally, we are ready to write our lexer. We'll try to match against any of the rules in our tokenList, failing which we will just assign the character to .Other.

Here's the method of interest:

func tokenize(input: String) -> [Token] {  
    var tokens = [Token]()
    var content = input

    while (content.characters.count > 0) {
        var matched = false

        for (pattern, generator) in tokenList {
            if let m = content.match(pattern) {
                if let t = generator(m) {
                    tokens.append(t)
                }

                content = content.substringFromIndex(content.startIndex.advancedBy(m.characters.count))
                matched = true
                break
            }
        }

        if !matched {
            let index = content.startIndex.advancedBy(1)
            tokens.append(.Other(content.substringToIndex(index)))
            content = content.substringFromIndex(index)
        }
    }
    return tokens
}

That's it for now! If you want to take a look at more code, this is all on Github. In the next post, we'll look at parsing and how we can build the AST.

To keep things simple we used a String extension to provide regex functionality via func match(String) -> String?. This is simply syntactic sugar over the NSRegularExpression API in Foundation:

var expressions = [String: NSRegularExpression]()  
public extension String {  
    public func match(regex: String) -> String? {
        let expression: NSRegularExpression
        if let exists = expressions[regex] {
            expression = exists
        } else {
            expression = try! NSRegularExpression(pattern: "^\(regex)", options: [])
            expressions[regex] = expression
        }

        let range = expression.rangeOfFirstMatchInString(self, options: [], range: NSMakeRange(0, self.utf16.count))
        if range.location != NSNotFound {
            return (self as NSString).substringWithRange(range)
        }
        return nil
    }
}

1) Use the HTML <img> tag
This means you can set its height and width which could result in a non-uniform scaling applied to each dimension.

2) Apply background-image via CSS
You have more control over how the image is displayed but now you have to consider classes and how you would apply them to your HTML content.

With React, we can simplify this by abstracting the implementation details into a reusable component. Ideally we want to use our component as if it was regular HTML markup:

<Image src={url} width={500} height={300} mode='fit' />  

This bit of JSX suggests we want to be able to set the image src, and dimensions via width and height. We also have mode which may be specified as fit or fill. This allows us to scale proportionally and crop the image appropriately.

Conveniently, CSS also exposes a similar attribute via background-size which can be specified as contain or cover.

Let's start with a typical React component template:

import React, {Component} from 'react';

export default class Image extends Component {  
  render() {
    return <div />
  }
}

Next we'll extract the necessary props and setup the CSS attributes as inline styles on our <div />:

import React, {Component} from 'react';

export default class Image extends Component {  
  render() {
    let {mode, src, height, width, style, ...props} = this.props;
    let modes = {
      'fill': 'cover',
      'fit': 'contain'
    };
    let size = modes[mode] || 'contain';

    let important = {
      backgroundImage: `url("${src}")`,
      backgroundSize: size,
      backgroundPosition: 'center center',
      backgroundRepeat: 'no-repeat'
    };

    return <div {...props} style={{...style, ...important}} />
  }
}

Here we're doing a couple of things:

1) We're using ES6's destructuring assignment feature to extract the props we're specifically interested to handle and coalesce the remaining props into the props variable.

2) We setup the CSS styles we require (mostly background- attributes.) ES6's template strings allow us to interpolate the url from src easily.

3) We use the spread operator ... to expand props into the <div /> element and also to merge style, which contains inline styles the parent component might have specified, with important, which contains the CSS styles needed for displaying the image. The order here is crucial because we want keys from important to override the same keys if they are specified in style.

Finally to make our component a bit more robust, let's add some default styles if they are not specified by the parent component:

import React, {Component} from 'react';

export default class Image extends Component {  
  render() {
    let {mode, src, height, width, style, ...props} = this.props;
    let modes = {
      'fill': 'cover',
      'fit': 'contain'
    };
    let size = modes[mode] || 'contain';

    let defaults = {
      height: height || 100,
      width: width || 100,
      backgroundColor: 'gray'
    };

    let important = {
      backgroundImage: `url("${src}")`,
      backgroundSize: size,
      backgroundPosition: 'center center',
      backgroundRepeat: 'no-repeat'
    };

    return <div {...props} style={{...defaults, ...style, ...important}} />
  }
}

This fixes the issue whereby if no height and width (or corresponding styles) are specified, we would end up with a zero-by-zero element. And there we have a functional and complete React element!

<MyVeryAwesomeComponent title="This is simply amazing!" />  

We can use props to solve the problem of building more general components by abstracting away more specific markup. Say we have a list of items - we can hide the implementation details by building a child component like this:

export default React.createClass({  
  render() {
    let items = this.props.items || []
    let rows = items.map(
      item => {
        return (
          <tr>
            <td>{item.title}</td>
          </tr>
        );
      }
    );

    return (
      <table>
        {rows}
      </table>
    );
  }
});

This way we can use this component like this:

<List items={items} />  

Now let's say we want to have 2 similar components like follows:

What do we do? We could duplicate this component and make the change in the one column, but that would violate DRY.

Instead, we can pass in the customizable portion in via props:

export default React.createClass({  
  render() {
    let items = this.props.items || []    
    let customComponent = this.props.customComponent || <span />

    let rows = items.map(
      item => {
        return (
          <tr>
            <td>{item.title}</td>
            <td>{customComponent}</td>
          </tr>
        );
      }
    );

    return (
      <table>
        {rows}
      </table>
    );
  }
});

Now we can create components like this:

<List items={items} customComponent={  
  <button>ADD</button>
} />

<List items={items} customComponent={  
  <div>
    <button>APPROVE</button><br />
    <button>REJECT</button>
  </div>
} />

This is an improvement over plain copy and paste, but now we've got a different problem. We can add an event handler (like onClick) to our customComponent but we've lost a the reference to the item in the table row.

To solve this, we need a way to communicate back from our child component to our parent component, since we map over items within the child.

We can do that by turning our prop into a callback like this:

export default React.createClass({  
  render() {
    let items = this.props.items || [];
    let customComponentGenerator = this.props.customComponentGenerator || function(){ return <span /> };

    let rows = items.map(
      item => {
        return (
          <tr key={item.title}>
            <td>{item.title}</td>
            <td>{customComponentGenerator(item)}</td>
          </tr>
        );
      }
    );

    return (
      <table>
        {rows}
      </table>
    );
  }
});

Now we can adjust the parent like this:

<List items={items} customComponentGenerator={  
  (item) => {
    return (
      <button onClick={
        ()=>console.log('add '+item.title)}>
        ADD
      </button>
      );
  }
} />

<List items={items} customComponentGenerator={  
  (item) => {
    return (
      <div>
        <button onClick={
         ()=>console.log('approve '+item.title)}>
         APPROVE
        </button><br />
        <button onClick={
          ()=>console.log('reject '+item.title)}>
          REJECT
        </button>
      </div>
      );
  }
} />

And that's a couple of ways we can build more generic components in React!

Let's revisit a loading spinner animation we've worked on before. If you want to see how this is implemented on iOS, check it out here.

Here's what we're aiming for:

Circles

Let's start by rendering something circular on the screen. We can do this using the border-radius attribute:

HTML

<div class="circle"></div>  

CSS

.circle {
  display: inline-block;
  background: #444;
  height: 80px;
  width: 80px;
  border-radius: 40px;
}

Here's what we get:

By setting the border radius of each quarter to the half the size of the element, we've rounded the square into a circle.

This is a great start but we don't have any ability to animate its appearance. To do any useful animation at all, we should consider semi-circle and apply some clipping to it. (If you want some additional reading, check out this link.)

Semi-circles

Let's create a semi-cirle:

HTML

<div class="container">  
  <div class="wedge"></div>
</div>  

CSS

.container {
  height: 80px;
  width: 80px;
  position: relative;
  display: inline-block;
}

.wedge {
  background: #444;
  height: 80px;
  width: 40px;
  border-radius: 0 40px 40px 0;
}

Here's what we get:

Again we use the border-radius attribute, but we've specified 0 for the top-left and bottom-left.

Animating semi-circles

Next let's apply an animation:

HTML

<div class="container">  
  <div class="wedge"></div>
</div>  

CSS

.container {
  ...
}

.wedge {
  background: #444;
  height: 80px;
  width: 40px;
  border-radius: 0 40px 40px 0;
  animation: wedge-animation 1.5s infinite linear;
  transform-origin: 0 50%;
}

@keyframes wedge-animation {
  0% {
    transform: rotateZ(-180deg);
  }
  50% {
    transform: rotateZ(0deg);
  }
  100% {
    transform: rotateZ(180deg);    
  }
}

Here's what we get:

We've setup a key-frame animation with the @keyframes keyword. To produce this rotation, we start at -180 degrees initially (0%), rotate to 0 degrees halfway through (50%) and finally end at 180 degrees (100%).

Next, we add this animation to our wedge class with a duration of 1.5 seconds, with a linear curve. We also move the transform-origin to the left-most position so it seems to rotate about the center of our "circle".

Clipping the semi-circle

We'll apply a clipping mask. We do this by wrapping our semi-circle in a parent <div/>:

HTML

<div class="container">  
  <div class="masking">
    <div class="wedge"></div>
  </div>
</div>  

CSS

.container {
  ...
}

.masking {
  width: 40px;
  overflow: hidden;
}

.wedge {
  ...
}

@keyframes wedge-animation {
  ...
}

Here's what we get:

Because we've made the parent <div/> as wide as the radius of the circle, as the semi-circle rotates past the origin it gets clipped. This is the crucial bit that makes the animation work - the shape seems to grow and shrink as it gets clipped.

Full circle

Next, we'll add the other half semi-circle:

HTML

<div class="container">  
  <div class="masking pushed">
    <div class="wedge wedge1"></div>
  </div>
  <div class="masking">
    <div class="wedge wedge2"></div>
  </div>
</div>  

CSS

...

.pushed {
  left: 40px;
}

.wedge {
  background: #444;
  height: 80px;
  width: 40px;
}

.wedge1 {
  border-radius: 0 40px 40px 0;
  animation: wedge-animation 1.5s infinite linear;
  transform-origin: 0 50%;
}

.wedge2 {
  border-radius: 40px 0 0 40px;
  animation: wedge-animation 1.5s infinite linear;
  transform-origin: 100% 50%;
}

@keyframes wedge-animation {
  ...
}

Here's what we get:

So we've duplicated our masking and wedge classes and specialized the wedge animation into wedge1 and wedge2 for each half of the circle. There's also a pushed class applied to wedge1 to move it over by the radius (it is the right semi-circle.)

Animation timing

The problem now is that we're using the exact same animation of each semi-circle. We need to delay the left semi-circle so both halves animate together seamlessly.

HTML

<div class="container">  
  <div class="masking pushed">
    <div class="wedge wedge1"></div>
  </div>
  <div class="masking">
    <div class="wedge wedge2"></div>
  </div>
</div>  

CSS

...

.wedge1 {
  border-radius: 0 40px 40px 0;
  animation: wedge1-animation 3.0s infinite linear;
  transform-origin: 0 50%;
}

.wedge2 {
  border-radius: 40px 0 0 40px;
  animation: wedge2-animation 3.0s infinite linear;
  transform-origin: 100% 50%;
}

@keyframes wedge1-animation {
  0% {
    transform: rotateZ(-180deg);
  }
  25%, 50% {
    transform: rotateZ(0deg);
  }
  75%, 100% {
    transform: rotateZ(180deg);
  }
}

@keyframes wedge2-animation {
  0%, 25% {
    transform: rotateZ(-180deg);
  }
  50%, 75% {
    transform: rotateZ(0deg);
  }
  100% {
    transform: rotateZ(180deg);
  }
}

Here's what we get:

What we've done is have the left semi-circle do nothing the first quarter duration and the right half animate in. In the next quarter, the right half does nothing and the left animates in. Finally, we animate the right half out, followed by the left. We've also doubled the animation duration to account for the delays.

From sector to edge

Next, we want to remove part of the circle such that we see only a thin border around the edge. We can't apply a circular mask, however. We can fake this by positioning another slightly smaller circle over the top of this shape.

HTML

<div class="container">  
  <div class="masking pushed">
    <div class="wedge wedge1"></div>
  </div>
  <div class="masking">
    <div class="wedge wedge2"></div>
  </div>
   <div class="overlay"></div>
</div>  

CSS

...

.overlay {
  background: white;
  border-radius: 50%;
  width: 76px;
  height: 76px;
  position: absolute;
  top: 2px;
  left: 2px;
}

We've added another <div/> which is 4px smaller in size. The border-radius is set to 50% which is half of the size. Finally we've set the background-color and positioned it absolutely to center it with respect to the circle behind.

Rotating everything

Finally, we'll apply a rotation to the entire hierarchy to get the look we're after.

HTML

<div class="container container-rotate">  
  <div class="masking pushed">
    <div class="wedge wedge1"></div>
  </div>
  <div class="masking">
    <div class="wedge wedge2"></div>
  </div>
   <div class="overlay"></div>
</div>  

CSS

...

.container-rotate {
  animation: container-rotate 3.0s infinite linear;
}

@keyframes container-rotate {
  0% {
    transform: rotateZ(0deg);
  }
  100% {
    transform: rotateZ(360deg);
  }
}

That's it! I hope you've enjoyed this post. In the following posts, we'll see how we can clean up our CSS and wrap our markup into a reusable component.

import Foundation

func +(lhs: NSURL, rhs:String) -> NSURL {  
    return lhs.URLByAppendingPathComponent(rhs)
}

This way you can simply use:

let url = NSURL(string: "http://google.com")!  
url \\ "http://google.com"  
url + "pages" \\ "http://google.com/pages"  

Some solutions make it really easy to make sense of JSON data. This is significant because Swift's strong type-safety makes it hard to work with JSON without much explicit casting:

• json-swift
• SwiftyJSON

Others go a step further and help make it easy to work with actual data models. They help to decode JSON strings or objects into native types (read Structs or Classes):

• Argo
• ObjectMapper
• JSONHelper

After a brief survey of available options, it felt like something was missing. We didn't have a complete solution that made the round trip - one that is able to produce native types from JSON and also JSON from native types.

Part of the reason, I suspected was the difficulty of extending types of data models, of which value types (read Structs) are becoming increasingly popular. This, however, changed in Swift 2.0 with the ability to write extensions on protocols.

So here's my take on the problem - JSONCodable.

It's by no means perfect - but I promise it will keep evolving as we discover better means of working with Swift.

Here's a quick run through of its features:

• It provides capabilities for encoding and decoding JSON
• It leverages features to expose an API as Swift-like as possible
• No operators were harmed in the making of this project

Still here? Let's take a look at how it works (you can also find this information on Github but I've tried to provide reasons for some of the implementation details here.)

JSONCodable is made of two seperate protocols JSONEncodable and JSONDecodable.

JSONEncodable generates Dictionarys (compatible with NSJSONSerialization) and Strings from your types while JSONDecodable creates structs (or classes) from compatible Dictionarys (from an incoming network request for instance.)

Suppose we have the following data models:

struct User {  
    var id: Int = 0
    var name: String = ""
    var email: String?
    var company: Company?
    var friends: [User] = []
}

struct Company {  
    var name: String = ""
    var address: String?
}

Encoding/Serialization

To encode JSON, we'll add conformance to JSONEncodable. You may also add conformance to JSONCodable.

extension User: JSONEncodable {  
    func JSONEncode() throws -> AnyObject {
        var result: [String: AnyObject] = [:]
        try result.archive(id, key: "id")
        try result.archive(name, key: "full_name")
        try result.archive(email, key: "email")
        try result.archive(company, key: "company")
        try result.archive(friends, key: "friends")
        return result
    }
}

extension Company: JSONEncodable {}  

The default implementation of func JSONEncode() inspects the properties of your type using reflection (see Company.) If you need a different mapping, you can provide your own implementation (see User.)

Using protocol extensions we can provide a default implementation that seems reasonable! That's great.

Decoding/Deserialization

To decode JSON, we'll add conformance to JSONDecodable. You may also add conformance to JSONCodable.

extension User: JSONDecodable {  
    mutating func JSONDecode(JSONDictionary: [String : AnyObject]) {
        JSONDictionary.restore(&id, key: "id")
        JSONDictionary.restore(&name, key: "full_name")
        JSONDictionary.restore(&email, key: "email")
        JSONDictionary.restore(&company, key: "company")
        JSONDictionary.restore(&friends, key: "friends")
    }
}

extension Company: JSONDecodable {  
    mutating func JSONDecode(JSONDictionary: [String : AnyObject]) {
        JSONDictionary.restore(&name, key: "name")
        JSONDictionary.restore(&address, key: "address")
    }
}

Unlike in JSONEncodable, you must provide the implementations for func JSONDecode(). As before, you can use this to configure the mapping between keys in the Dictionary to properties in your Structs and Classes.

We can't provide a default implementation of this because there's no way in Swift to dynamically set property values at runtime. The best we can do is use inout parameters (some have tried to obfuscate this using operators - Sigh)

Limitations

• Your types must be initializable without any parameters, i.e. implement init(). You can do this by either providing a default value for all your properties or implement init() directly and configuring your properties at initialization.

• You must use var instead of let when declaring properties.

JSONDecodable needs to be able to create new instances of your types and set their values thereafter. So we need to a standard way to initialize these types via init() and the properties must be mutable to allow setting their values.

What's next?

• Ideally we'd allow for properties to be constant - which really might make sense for some situations. However, we then need some way of performing a complete initialization of the type (which introduces some ugliness in the API because consumers need to provide a non-trivial initializer.)

• More symmetry in the API regarding errors when encoding and decoding JSON.

If you have any thoughts, let me know here or on twitter @matthewcheok!

extension UIFont {  
    var proportionalFont: UIFont {
        let settings = [
            [
                UIFontFeatureTypeIdentifierKey: kNumberSpacingType,
                UIFontFeatureSelectorIdentifierKey: kProportionalNumbersSelector
            ],
            [
                UIFontFeatureTypeIdentifierKey: kCharacterAlternativesType,
                UIFontFeatureSelectorIdentifierKey: 1
            ]
        ]
        let descriptor = self.fontDescriptor().fontDescriptorByAddingAttributes([
            UIFontDescriptorFeatureSettingsAttribute: settings
            ])
        return UIFont(descriptor: descriptor, size: self.pointSize)
    }
}

The above category generates a font (where available) that has proportionally spaced digits and uses alternative glyphs for certain punctuation symbols where appropriate.

We could do this by breaking up the String representation of the url and creating a Dictionary. I've wrapped that up in a convenient extension to NSURL:

extension NSURL {  
    var queryDictionary: [String:String]? {
        if let query = self.query {
            var dict = [String:String]()
            for parameter in query.componentsSeparatedByString("&") {
                let components = parameter.componentsSeparatedByString("=")
                if components.count == 2 {
                    let key = components[0].stringByReplacingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
                    let value = components[1].stringByReplacingPercentEscapesUsingEncoding(NSUTF8StringEncoding)!
                    dict[key] = value
                }
            }
            return dict
        }
        else {
            return nil
        }
    }
}

I built Jibber because debugging JSON requests in Xcode was infuriatingly painful. If you work with RESTful API, do check it out!

Starting with a new project, add a UIView to the storyboard and added subclass called SpinningView. Next, we need to show a circle. I'll opt to use a CAShapeLayer as that gives us more flexibility with animation.

class SpinningView: UIView {

    let circleLayer = CAShapeLayer()

    override init(frame: CGRect) {
        super.init(frame: frame)
        setup()
    }

    required init(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder)
    }

    override func awakeFromNib() {
        super.awakeFromNib()
        setup()
    }
}

Most of the above code is boilerplate. We create a constant property, circleLayer and initialize it right away so we can forget about working with Optionals. Next we need to find a hook to add it to the view/layer hierarchy. For views instantiated programmatically, this is clearly init(frame:). But if we happen to add this in the storyboard and set the Custom Class in Interface Builder, this won't work. So another option is to use awakeFromNib().

func setup() {  
    circleLayer.lineWidth = 4
    circleLayer.fillColor = nil
    circleLayer.strokeColor = UIColor(red: 0.8078, green: 0.2549, blue: 0.2392, alpha: 1.0).CGColor
    layer.addSublayer(circleLayer)
}

I've refactored the setup into a method called (you guessed it) setup() and added the call to it in both methods.

override func layoutSubviews() {  
    super.layoutSubviews()

    let center = CGPoint(x: bounds.midX, y: bounds.midY)
    let radius = min(bounds.width, bounds.height) / 2 - circleLayer.lineWidth/2

    let startAngle = CGFloat(-M_PI_2)
    let endAngle = startAngle + CGFloat(M_PI * 2)
    let path = UIBezierPath(arcCenter: CGPointZero, radius: radius, startAngle: startAngle, endAngle: endAngle, clockwise: true)

    circleLayer.position = center
    circleLayer.path = path.CGPath
}

Next, we configure some layer properties to show the circle. Because we're drawing the circle using a path, we can simply set lineWidth to however thick we want the line to be. We also clear out the fillColor and set the strokeColor. Note the two properties take a CGColor not UIColor.

All we need to do now is configure the path object itself. We want to the circle to be as big as the view so it will draw itself at the right size when the view is resized. We do this in layoutSubviews(). We calculate the center position halfway between the width and height of the bounds. Because we want the circle to fit within the view, the radius can't be bigger than the view's width or height. We take the smaller of them and halve it. Finally we need to subtract half of the lineWidth because the stroke draws outward from the center of the path.

To make things simple later on, let's have the path draw from the top-most position and run clockwise. If you remember enough geometry, angles are measured from the positive x-axis and go clockwise. So we start at -M_PI_2 or -90 degrees.

Build and run and you should see a red circle:

Let's take advantage of some of the new features and make debugging our custom view a bit more manageable. Let's have the view display in Interface Builder:

@IBDesignable
class SpinningView: UIView {  
    ...

    override func prepareForInterfaceBuilder() {
        super.prepareForInterfaceBuilder()
        setup()
    }
}

By providing the @IBDesignable attribute and the prepareForInterfaceBuilder() method, we tell Xcode to draw our view's custom appearance in Interface Builder. You can test this out by going to the storyboard.

Next we can adopt the tintColor attribute by implementing the following:

func setup() {  
    ...
    tintColorDidChange()
}

override func tintColorDidChange() {  
    super.tintColorDidChange()
    circleLayer.strokeColor = tintColor.CGColor
}

Go into the storyboard and see the circle change color. Change the Tint in the Attributes Inspector and notice how the color changes.

We'll expose one more property to control the lineWidth:

@IBInspectable var lineWidth: CGFloat = 4 {
    didSet {
        circleLayer.lineWidth = lineWidth  
        setNeedsLayout()        
    }
}

func setup() {  
    circleLayer.lineWidth = lineWidth
    ...
}

Have a go at changing the property in the Attributes Inspector. The @IBDesignable and @IBInspectable attributes make it really easy to debug custom views!

Alright, let's get into the meat of the experiment and have a try at animating the circle. The animation can be broken down into a few parts.

• The stroke is animated from the beginning of the path to the end of the path. This animation can be broken up further.
  • The end position of the stroke is animated from the beginning of the path to the end of the path.
  • The start position of the stroke is animated from the beginning of the path to the end of the path.
• The circle itself is put into rotation.

Let's start with the strokeEnd animation:

let strokeEndAnimation: CAAnimation = {  
    let animation = CABasicAnimation(keyPath: "strokeEnd")
    animation.fromValue = 0
    animation.toValue = 1
    animation.duration = 2
    animation.timingFunction = CAMediaTimingFunction(name: kCAMediaTimingFunctionEaseInEaseOut)
    animation.repeatCount = MAXFLOAT
    return animation
    }()

The strokeEnd and strokeStart properties take a value from 0 (beginning of the path) to 1 (end of the path). We're also using a timing function of ease-in-ease-out to make the animation a bit more natural-looking. Finally, the repeatCount is the number of times the animation will repeat. We'll just set this to a large number.

Next we'll add a property to control this growing animation:

@IBInspectable var animating: Bool = true {
    didSet {
        updateAnimation()
    }
}

func setup() {  
    ...

    tintColorDidChange()
    updateAnimation()
}

func updateAnimation() {  
    if animating {
        circleLayer.addAnimation(strokeEndAnimation, forKey: "strokeEnd")
    }
    else {
        circleLayer.removeAnimationForKey("strokeEnd")
    }
}

Build and run and you should see the following:

Next, we'll add animation for strokeStart so the stroke shrinks at the other end as it grows clockwise. However, we need to sort of delay the shrinking so it won't shrink at the same rate it grows. We need to create an animation group to add this delay.

let strokeEndAnimation: CAAnimation = {  
    let animation = CABasicAnimation(keyPath: "strokeEnd")
    animation.fromValue = 0
    animation.toValue = 1
    animation.duration = 2
    animation.timingFunction = CAMediaTimingFunction(name: kCAMediaTimingFunctionEaseInEaseOut)

    let group = CAAnimationGroup()
    group.duration = 2.5
    group.repeatCount = MAXFLOAT
    group.animations = [animation]

    return group
    }()

let strokeStartAnimation: CAAnimation = {  
    let animation = CABasicAnimation(keyPath: "strokeStart")
    animation.beginTime = 0.5
    animation.fromValue = 0
    animation.toValue = 1
    animation.duration = 2
    animation.timingFunction = CAMediaTimingFunction(name: kCAMediaTimingFunctionEaseInEaseOut)

    let group = CAAnimationGroup()
    group.duration = 2.5
    group.repeatCount = MAXFLOAT
    group.animations = [animation]

    return group
    }()

func updateAnimation() {  
    if animating {
        circleLayer.addAnimation(strokeEndAnimation, forKey: "strokeEnd")
        circleLayer.addAnimation(strokeStartAnimation, forKey: "strokeStart")
    }
    else {
        circleLayer.removeAnimationForKey("strokeEnd")
        circleLayer.removeAnimationForKey("strokeStart")
    }
}    

Build and run and you should see the following:

Finally, we'll add the rotation for a last bit of polish.

let rotationAnimation: CAAnimation = {  
      let animation = CABasicAnimation(keyPath: "transform.rotation.z")
      animation.fromValue = 0
      animation.toValue = M_PI * 2
      animation.duration = 4
      animation.repeatCount = MAXFLOAT
      return animation
      }()

func updateAnimation() {  
    if animating {
        circleLayer.addAnimation(strokeEndAnimation, forKey: "strokeEnd")
        circleLayer.addAnimation(strokeStartAnimation, forKey: "strokeStart")
        circleLayer.addAnimation(rotationAnimation, forKey: "rotation")
    }
    else {
        circleLayer.removeAnimationForKey("strokeEnd")
        circleLayer.removeAnimationForKey("strokeStart")
        circleLayer.removeAnimationForKey("rotation")
    }
}

And there we have it - a Material Design-styled loading spinner!

Creating natural looking animations has always been hard. But with Pop and its extension MCAnimate, it doesn't have to be. (Disclaimer: I maintain the MCAnimate category.)

Today, we'll go ahead to recreate an animation by Andy Barnard from his post Animation Timing on iOS (if you're into serious animation on iOS, it's definitely worth a read.)

Firstly, we'll create views for each of the red circles and then store them away in an array:

CGPoint center = CGPointMake(CGRectGetWidth(self.view.bounds) / 2, CGRectGetHeight(self.view.bounds) / 2);

NSMutableArray *circles = [NSMutableArray array];

for (int i = 0; i < kNumberOfCircles; i++) {  
    UIView *circle = [[UIView alloc] initWithFrame:CGRectMake(0, 0, kCircleSize, kCircleSize)];
    circle.backgroundColor = [UIColor colorWithRed:0.945 green:0.439 blue:0.416 alpha:1];
    circle.layer.cornerRadius = kCircleSize / 2;
    circle.center = center;
    circle.alpha = 0;
    circle.scaleXY = CGPointMake(0.5, 0.5);

    [self.view addSubview:circle];
    [circles addObject:circle];
}

self.circles = [circles copy];  

We're simply using the cornerRadius property on CALayer to give the impression of a circle. We then start the circles off with a smaller scale and make them fully transparent.

In the first stage of the animation, we move the circles out to a certain radius, scale them up to full size, and make them visible. But each circle is slightly delayed to create a staggered animation. This is achieved using the beginTime property (specifying the delay in seconds) in Core Animation and Pop. In MCAnimate, this is really trivial:

[circles sequenceWithInterval:0.1 animations:^(UIView *circle, NSInteger index){
    CGPoint position = center;
    position.x += kCircleRadius * sin(angleIncrement * index);
    position.y -= kCircleRadius * cos(angleIncrement * index);

    circle.spring.center = position;
    circle.spring.alpha = 1;
    circle.spring.scaleXY = CGPointMake(1, 1);
} completion:^(BOOL finished){
}];

Having specified the interval between animations, the library knows how to iterate through the array applying animations to each element. For convenience, the element and its index in the array is provided as parameters to the animation block.

What's left is essentially a trigonometric problem - using sin() and cos() to determine the position around a circle's center.

In the next stage, we move the circle elements out further still (at twice the initial radius):

[circles sequenceWithInterval:0 animations:^(UIView *circle, NSInteger index){
    CGPoint position = center;
    position.x += 2 * kCircleRadius * sin(angleIncrement * index);
    position.y -= 2 * kCircleRadius * cos(angleIncrement * index);

    circle.spring.center = position;
} completion:^(BOOL finished){            
}];            

This time we are using an interval of 0 to have the elements animate all at the same time.

Next, we animate the elements a step anti-clockwise and then back:

[circles sequenceWithInterval:0 animations:^(UIView *circle, NSInteger index){
    CGPoint position = center;
    position.x += 2 * kCircleRadius * sin(angleIncrement * (index-1));
    position.y -= 2 * kCircleRadius * cos(angleIncrement * (index-1));

    circle.spring.center = position;
} completion:^(BOOL finished){
    [circles sequenceWithInterval:0 animations:^(UIView *circle, NSInteger index){
        CGPoint position = center;
        position.x += 2 * kCircleRadius * sin(angleIncrement * index);
        position.y -= 2 * kCircleRadius * cos(angleIncrement * index);

        circle.spring.center = position;
    } completion:^(BOOL finished){
    }];
}];

Here's where the index parameter comes in handy. We simply subtract 1 to calculate the position of the previous element (which gives the effect of moving anti-clockwise).

And finally, we reverse the initial animation, moving all elements back to the center, scaling them down and making them transparent:

[circles sequenceWithInterval:0.1 animations:^(UIView *circle, NSInteger index){
    circle.spring.center = center;
    circle.spring.alpha = 0;
    circle.spring.scaleXY = CGPointMake(0.5, 0.5);
} completion:nil];

I hope you enjoyed the short breakdown. Check out the demo project to see this in action.

Download it for free on the App Store

Design Decisions

The screen is your playlist.

For Offbeat, I wanted an extremely simple UI where the screen is simply the playlist. Tap on an item to play.

Swipe an item to left or right to remove from the playlist.

A fun way to randomize a playlist.

Because the concept is rather simple, the most obvious way to select a tempo might be to use a slider:

However, this probably might have been no fun at all and made for a poor user experience. Instead I opted to use color to give a sense of speed (magnitude of the tempo). The circular motion also might be familar to those who used the Click Wheel on the classic iPod.

Here's how you can scrub through to find a playlist with the right tempo:

And to take the interactions up a notch, you can also start tapping on the scrubbing control (or Tempo Dial) to physically tell the app your preferred tempo:

Provide hints for new interactions.

Because the Tempo Dial is something unfamiliar to users (they are not likely to have seen it before in other apps.) I decided to provide a fun-looking hint in the form a moving glow around the control to encourage the scrubbing interaction:

I also fade between the verbs "scrub" and "tap" to show the different interactions that are possible.

I hope you liked this short discussion. Let me know what you think in the comments.

The following is a chapter from my upcoming book, Design Teardowns: Step-by-step iOS interface design walkthroughs. If you like this or have a suggestion for another UI teardown, let me know or join my mailing list and get access to the sample code.

Goal

We are going to recreate the spinning tips effect from the onboarding of Tweetbot. The final result looks something like this:

Observations

The tip bounces in from the side.

The onboarding process begins by having the first tip bounce in from the right. The tip also seems to rotate as it comes into view.

Touching anywhere on the screen pulls at the tip.

Pulling anywhere on the screen seems to pull the tip in that direction. Also it seems like the tip moves in such a way that seems to suggest its rotating around a point which is somewhere off-screen.

Moving between tips is fluid.

As one tip moves off-screen, the next appears from the opposite direction in what makes for a really fluid interaction.

Prerequisites

This teardown requires Xcode 6 and above and resulting project works on iOS 8 and above. You should also know the following concepts:

Xcode Basics

You should know your way around Xcode including how to create projects and classes, and access files, navigators and inspectors. You should also know how to create outlets and actions in interface builder (check out the previous teardown if you don't already know this.)

UIKit Basics

You should know how to create views (in code and in Interface Builder) as well as how to manipulate properties on UIView and its subclasses. You should also know how to use Auto Layout.

Game Plan

We'll adopt UIKit's built-in physics system, UIDynamicAnimator and experiment with some of the behaviors available such as UISnapBehavior and UIAttachmentBehavior.

Blueprint

Creating the Model

Create a new Xcode project with the Single View Application template. Next we're going to create the data model that represents each tip. Create a new swift file named Tip.swift and add the following definition:

import UIKit

struct Tip {  
    let title: String
    let summary: String
    let image: UIImage?
}

This simple model includes properties for the tip's title, summary and image to be displayed. We've chosen to make the image property optional which will make it easier to work with UIKit.

Creating the UI

Next we will create the view hierarchy to display the above model properties. Create a new file, select the template from iOS, User Interface, View.

Add 2 labels, an image view and a page control as follows:

Note the mode for the image view has been set to Aspect Fill and the vertical Content Compression Resistance in the Size Inspector to be lower than that of the next label (this will allow the image view to shrink before the label does).

The number of lines in the second label is set to 0 to allow word wrap. Add the relevant Auto Layout constraints to allow the view to adapt to any arbitrary size.

Next we will create a backing subclass for this view. Create a new subclass of UIView called TipView.

Add the following outlets to the class by setting up the connections with Interface Builder:

@IBOutlet weak var titleLabel: UILabel!
@IBOutlet weak var summaryLabel: UILabel!

@IBOutlet weak var imageView: UIImageView!
@IBOutlet weak var pageControl: UIPageControl!

Add the following property of our data model Tip and the corresponding property observer to update our subviews accordingly:

var tip: Tip? {  
    didSet {
        titleLabel.text = tip?.title ?? "No Title"
        summaryLabel.text = tip?.summary ?? "No Summary"
        imageView.image = tip?.image
    }
}

Note the ?? operator (also known as the coalescing operator). We can use this operator to provide default values when there is no model available.

Next we'll add rounded corners to the this view:

override func layoutSubviews() {  
    super.layoutSubviews()
    layer.cornerRadius = 10
    layer.masksToBounds = true
}

Setting up the View Controller

Now we are ready to present our tips. We want a general way to do this so we can present tips from any screen in the application. In order to do this, we'll create a dedicated view controller for displaying tips and then present this view controller from wherever we require.

Create TipViewController as a subclass of UIViewController.

Next we'll add couple of constants to keep track of some layout attributes:

private let kTipViewHeight: CGFloat = 400  
private let kTipViewWidth: CGFloat  = 300  

Now when the view controller loads, we will create a TipView and display it on the screen. First add this utility method that creates a tip view and configures it:

func createTipView() -> TipView? {  
    if let view = UINib(nibName: "TipView", bundle: nil).instantiateWithOwner(nil, options: nil).first as TipView? {
        view.frame = CGRect(x: 0, y: 0, width: kTipViewWidth, height: kTipViewHeight)
        return view
    }
    return nil
}

UINib gives us programmatic access to the Interface Builder xib file we created earlier. Instantiating this file gives us an array of objects and we are interested in the first (and only) top level view.

Next what we need to do is to simply center the view in the middle of the screen and add it to the view hierarchy:

override func viewDidLoad() {  
    super.viewDidLoad()
    if let tipView = createTipView() {
        var center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)
        tipView.center = center
        view.addSubview(tipView)
    }
}

We're almost ready to test out our work so far. Before that, we'll add a convenience method to present the tip view controller. Add the following below the entire class definition:

extension UIViewController {  
    func presentTips(tips: [Tip], animated: Bool, completion: (() -> Void)?) {
        let controller = TipViewController()
        controller.modalTransitionStyle = .CrossDissolve
        presentViewController(controller, animated: animated, completion: completion)
    }
}

Extensions are a way of adding new functionality to existing types and classes in Swift. They are almost equivalent to Categories in Objective-C.

This makes it as easy to present tips as presenting a regular modal view controller on UIViewController.

We're simply going to take an array of tips to display (but we are not yet doing anything to display them) and configure the type of model presentation we need. Using a presentation transition of CrossDissolve will simply fade the tips view controller into view.

Back in ViewController.swift we will display the tips view controller immediately on launch:

override func viewDidAppear(animated: Bool) {  
    super.viewDidAppear(animated)
    presentTips([], animated: true, completion: nil)
}

Build and run the project and you should see the following:

Adding the animations

To recreate the effect in Tweetbot, we will place the initial tip off-screen and rotated, and then have it snap back into the center of the screen:

To do this, we'll first add a couple of properties to our view controller:

var tipView: TipView!  
var animator: UIDynamicAnimator!  
var attachmentBehavior: UIAttachmentBehavior!  
var snapBehavior: UISnapBehavior!  

These properties will hold references to the tip view and the necessary physics constraints.

We'll also add another constant to hold the offset parameter about which the tip view rotates around:

private let kTipViewOffset: CGFloat = 500  

Next we will create an enumeration to hold the states of the tip view that we're interested in:

enum TipViewPosition: Int {  
    case Default
    case RotatedLeft
    case RotatedRight

    func viewCenter(var center: CGPoint) -> CGPoint {
        switch self {
        case .RotatedLeft:
            center.y += kTipViewOffset
            center.x -= kTipViewOffset

        case .RotatedRight:
            center.y += kTipViewOffset
            center.x += kTipViewOffset

        default:
            ()
        }

        return center
    }

    func viewTransform() -> CGAffineTransform {
        switch self {
        case .RotatedLeft:
            return CGAffineTransformMakeRotation(CGFloat(-M_PI_2))

        case .RotatedRight:
            return CGAffineTransformMakeRotation(CGFloat(M_PI_2))

        default:
            return CGAffineTransformIdentity
        }
    }
}

The enumeration also has some convenience methods for calculating the center and transform of the tip view.

We're using a CGAffineTransform as a means of specifying the rotation. This is usually represented as a transformation matrix. However, for our purposes, we are going to treat this as an opaque value (and just use the provided functions to manipulate it.)

Next we will add methods to place the tip view in position. The method updateTipView() simply sets the center and transform properties on the tip view:

func updateTipView(tipView: UIView, position: TipViewPosition) {  
    var center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)
    tipView.center = position.viewCenter(center)
    tipView.transform = position.viewTransform()
}

The next one resetTipView() removes all behaviors from the physics engine, updates the tip view position and updates the physics engine with new position. We then add back the necessary behaviors.

func resetTipView(tipView: UIView, position: TipViewPosition) {  
    animator.removeAllBehaviors()

    updateTipView(tipView, position: position)
    animator.updateItemUsingCurrentState(tipView)

    animator.addBehavior(attachmentBehavior)
    animator.addBehavior(snapBehavior)
}

We use updateItemUsingCurrentState to reset the animator's state to the view's current state. This works best if no behaviors are attached.

Next we will add a method to setup the physics engine:

func setupAnimator() {  
    animator = UIDynamicAnimator(referenceView: view)

    var center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)

    tipView = createTipView()
    view.addSubview(tipView)
    snapBehavior = UISnapBehavior(item: tipView, snapToPoint: center)

    center.y += kTipViewOffset
    attachmentBehavior = UIAttachmentBehavior(item: tipView, offsetFromCenter: UIOffset(horizontal: 0, vertical: kTipViewOffset), attachedToAnchor: center)

    resetTipView(tipView, position: .RotatedRight)
}

We've created the animator and assigned our view controller's root view to be the reference view (for calculation in the physics simulations.)

Next we've created a snap behavior that will bring the tip view back into the center of the root view. Most importantly we've created an attachment behavior (which you can imagine as sort of invisible string) that connects the tip view to an imaginary point of distance kTipViewOffset directly below it.

Now clear out the previous testing code in viewDidLoad() and add the following to viewDidAppear():

override func viewDidAppear(animated: Bool) {  
    super.viewDidAppear(animated)
    setupAnimator()
}

Build and run the project and you should see the following:

Now we notice a slight quirk. Auto Layout is resizing the contents of our tip view during the animation.

As the tip view is rotating, its frame is significantly larger than its bounds (it's the smallest rectanglar region that will fit the view within it). Since Auto Layout sizes views according to their frames, it incorrectly assumes it has a larger space to lay things out.

To correct this we need to supply the method alignmentRectForFrame() in the view subclass. Add the following to TipView:

override func alignmentRectForFrame(frame: CGRect) -> CGRect {  
    return bounds
}

Build and run and things should look right:

Adding the interactions

To handle the dragging interaction, we'll create a pan gesture recognizer and add it to the view controller's root view. Add the following to the bottom of setupAnimator:

let pan = UIPanGestureRecognizer(target: self, action: "panTipView:")  
view.addGestureRecognizer(pan)  

Add a new property to contain the attachment behavior managed by the pan gesture:

var panBehavior: UIAttachmentBehavior!  

Next we'll add the method to handle updates when the pan gesture is triggered. We need to do a few things:

1. When the pan gesture begins, we remove the snap behavior (so we can move the tip view without it snapping back to the center of the screen). We then create an attachment behavior anchored to the touch location.

2. As the pan gesture continues, we change the anchor of the previous attachment behavior to the current touch location. This will adjust the tip view position until it satisfies both attachment constraints (the initial one with the offset distance and this panning one).

3. When the pan gesture stops (it either ends or is cancelled by the system), we have to decide if we should proceed with the transition or cancel it. One way to do this is to just look at how far we have moved (the offset from the center).

4. If we cancel the transition, we remove the pan gesture's attachment behavior and add the snap behavior back to the view (which will snap it back to the center of the screen).

5. If we proceed with the transition, we first change the attachment's anchor to be off-screen in the right direction to animate the view away. Next we call resetTipView to bring it back on-screen from the opposite direction.

func panTipView(pan: UIPanGestureRecognizer) {  
    let location = pan.locationInView(view)

    switch pan.state {
    case .Began:
        animator.removeBehavior(snapBehavior)
        panBehavior = UIAttachmentBehavior(item: tipView, attachedToAnchor: location)
        animator.addBehavior(panBehavior)

    case .Changed:
        panBehavior.anchorPoint = location

    case .Ended:
        fallthrough
    case .Cancelled:
        let center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)
        let offset = location.x - center.x
        if fabs(offset) < 100 {
            animator.removeBehavior(panBehavior)
            animator.addBehavior(snapBehavior)
        }
        else {
            let position = offset > 0 ? TipViewPosition.RotatedRight : TipViewPosition.RotatedLeft
            let nextPosition = offset > 0 ? TipViewPosition.RotatedLeft : TipViewPosition.RotatedRight
            let duration = 0.4

            let center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)

            panBehavior.anchorPoint = position.viewCenter(center)
            dispatch_after(dispatch_time(
                DISPATCH_TIME_NOW, Int64(duration * Double(NSEC_PER_SEC))), dispatch_get_main_queue()) {
                    [self]
                    self.resetTipView(self.tipView, position: nextPosition)
            }
        }

    default:
        ()
    }
}

The empty parentheses () are the simpliest way to include a statement in Swift. We use this to provide no operation in the default case.

Build and run and try to move the tip view around:

Making the Model Work

Finally we're ready to use actual tips. Let's add some sample data to the our presenting view controller in ViewController.swift:

presentTips([  
      Tip(title: "Tip #1: Don't Blink", summary: "Fantastic shot of Sarah for the ALS Ice Bucket Challenge - And yes, she tried her hardest not to blink!", image: UIImage(named: "als-ice-bucket-challenge")),
      Tip(title: "Tip #2: Explore", summary: "Get out of the house!", image: UIImage(named: "arch-architecture")),
      Tip(title: "Tip #3: Take in the Moment", summary: "Remember that each moment is unique and will never come again.", image: UIImage(named: "man-mountains"))
], animated: true, completion: nil)

Add the following properties to TipViewController to keep track of the tips and which one is being shown:

var tips = [Tip]()  
var index = 0  

Now we've got to remember to save the tips away as our view controller is presented:

func presentTips(tips: [Tip], animated: Bool, completion: (() -> Void)?) {  
    let controller = TipViewController()
    controller.tips = tips

    ...
}

Next we need to setup the view given an instance of the Tip data model. We also need to adjust the page control accordingly. Add this method to the TipViewController to setup the tip view given an index into our list of tips:

func setupTipView(tipView: TipView, index: Int) {  
    if index < tips.count {
        let tip = tips[index]
        tipView.tip = tip

        tipView.pageControl.numberOfPages = tips.count
        tipView.pageControl.currentPage = index
    }
    else {
        tipView.tip = nil
    }
}

Let's load the very first tip when we setup the animator:

func setupAnimator() {  
    ...

    setupTipView(tipView, index: 0)
    resetTipView(tipView, position: .RotatedRight)

    ...
}

Finally we need to handle moving between tips as we interact with the tip view. Add the following the .Changed state of the pan gesture method:

...
else {  
    var nextIndex = self.index
    var position = TipViewPosition.RotatedRight
    var nextPosition = TipViewPosition.RotatedLeft

    if offset > 0 {
        nextIndex -= 1
        nextPosition = .RotatedLeft
        position = .RotatedRight
    }
    else {
        nextIndex += 1
        nextPosition = .RotatedRight
        position = .RotatedLeft
    }

    if nextIndex < 0 {
        nextIndex = 0
        nextPosition = .RotatedRight
    }

    let duration = 0.4
    let center = CGPoint(x: CGRectGetWidth(view.bounds)/2, y: CGRectGetHeight(view.bounds)/2)

    panBehavior.anchorPoint = position.viewCenter(center)

    dispatch_after(dispatch_time(
        DISPATCH_TIME_NOW, Int64(duration * Double(NSEC_PER_SEC))), dispatch_get_main_queue()) {
            [self]
            if nextIndex >= self.tips.count {
                self.dismissViewControllerAnimated(true, completion: nil)
            }
            else {
                self.index = nextIndex
                self.setupTipView(self.tipView, index: nextIndex)
                self.resetTipView(self.tipView, position: nextPosition)
            }
    }
}

If we try to swipe to the previous tip when we are already at the first tip, we simply want to bounce back. If we try to swipe after the last one, we'll dismiss the tip view controller.

We can improve the visual effect by making the presenting view controller slightly visible. Make the tips view controller's background color semi-transparent:

override func viewDidLoad() {  
    super.viewDidLoad()
    view.backgroundColor = UIColor(white: 0, alpha: 0.5)
}

Add the following bit to presentTips() in our UIViewController extension:

func presentTips(tips: [Tip], animated: Bool, completion: (() -> Void)?) {  
    ...

    controller.modalPresentationStyle = .OverFullScreen
    controller.modalTransitionStyle = .CrossDissolve
    presentViewController(controller, animated: animated, completion: completion)
}

By specifying OverFullScreen as the modalPresentationStyle, we are telling the system to keep the presenting view controller in the view hierarchy. Without this, you'd just see a black background.

Now build and run and you should see the following:

Afterthoughts

That's it, we've created the Spinning Tips effect. You've learnt how to:

• Setup and configure UIDynamicAnimator
• Use attachments and snap behaviors
• Create a view controller that can be used generally

Next Steps

To add more polish you can try the following:

• Experiment with resistance property of UIDynamicItemBehavior to adjust the speed of the animation according to the velocity of the pan gesture.

If you liked this teardown, want to receive updates on the book, or want to play with the sample code subscribe to my mailing list (your email will not be shared):