Arrow 🏹 - Elegant JSON Parsing in Swift
Reason - Example - Installation
identifier <-- json["id"]
name <-- json["name"]
stats <-- json["stats"]
Reason
Why
Because parsing JSON in Swift is full of unecessary if lets, obvious casts and nil-checks
There must be a better way
How
By using a simple arrow operator that takes care of the boilerplate code for us.
Json mapping code becomes concise and maintainable ❤️
What
- [x] Simple & Lightweight (~200lines)
- [x] Pure Swift
- [x] Leaves your models clean
- [x] Implicitly casts JSON values to the right types in your model
- [x] Automatic NSDate, NSURL, Enum, Custom model Parsing
- [x] Converts string values to numeric types in your model
- [x] Does not crash if JSON key is not there, nor returns nil, it simply doesn’t do anything
- [x] No overly complex obscure functional chaining operator overloading voodoo magic ?==:>>><> 😅
Example
Swift Model
struct Profile {
var identifier = 0
var name = ""
var link:NSURL?
var weekday:WeekDay = .Monday
var stats = Stats()
var phoneNumbers = [PhoneNumber]()
}
JSON File
{
"id": 15678,
"name": "John Doe",
"link": "https://apple.com/steve",
"weekdayInt" : 3,
"stats": {
"numberOfFriends": 163,
"numberOfFans": 10987
},
"phoneNumbers": [{
"label": "house",
"number": "9809876545"
}, {
"label": "cell",
"number": "0908070656"
}, {
"label": "work",
"number": "0916570656"
}]
}
Before (Chaos)
var profile = Profile()
// Int
if let id = json["id"] as? Int {
profile.identifier = id
}
// String
if let name = json["name"] as? String {
profile.name = name
}
// NSURL
if let link = json["link"] as? String, url = NSURL(string:link) {
profile.link = link
}
// Enum
if let weekdayInt = json["weekdayInt"] as? Int, weekday = WeekDay(rawValue:weekdayInt) {
profile.weekday = weekday
}
// Custom nested object
if let statsJson = json["stats"] as? AnyObject {
if let numberOfFans = statsJson["numberOfFans"] as? Int {
profile.stats.numberOfFans = numberOfFans
}
if let numberOfFriends = statsJson["numberOfFriends"] as? Int {
profile.stats.numberOfFriends = numberOfFriends
}
}
// Array of custom nested object
if let pns = json["phoneNumbers"] as? [AnyObject] {
for pn in pns {
phoneNumbers.append(PhoneNumber(json: pn))
}
}
After 🎉🎉🎉
extension Profile:ArrowParsable {
mutating func deserialize(json: JSON) {
identifier <-- json["id"]
link <-- json["link"]
name <-- json["name"]
weekday <-- json["weekdayInt"]
stats <- json["stats"]
phoneNumbers <-- json["phoneNumbers"]
}
}
Usage
let profile = Profile()
profile.deserialize(json)
Installation
Carthage
github "s4cha/Arrow"
CocoaPods
pod 'Arrow'
use_frameworks!
Manually
Simply Copy and Paste Arrow.swift in your Xcode Project :)
https://github.com/s4cha/Arrow/blob/master/Arrow.swift
As A Framework
Grab this repository and build the Framework target on the example project. Then Link against this framework.
How Does That Work
Notice earlier we typed :
stats <-- json["stats"]
That’s because we created and extension Stats+Arrow.swift
enabling us to use the Arrow Operator
// Stats+Arrow.swift
import Foundation
extension Stats:ArrowParsable {
mutating func deserialize(json: JSON) {
numberOfFriends <-- json["numberOfFriends"]
numberOfFans <-- json["numberOfFans"]
}
}
Flexible you said
- DO I have to use the <– for my sub models
- Nope, you could write it like so if you wanted :
stats.numberOfFriends <-- json["stats.numberOfFriends"]
stats.numberOfFans <-- json["stats.numberOfFans"]
- Hey I don’t want to parse NSDates in every files, do you have something for me?
Sure, just set your date format once and you’re done.
// Configure NSDate Parsing
Arrow.setDateFormat("yyyy-MM-dd'T'HH:mm:ssZZZZZ")
Arrow.setUseTimeIntervalSinceReferenceDate(true)
// Dates can be parsed form custom date format or timestamp
let json:JSON = JSON(["date": "2013-06-07T16:38:40+02:00", "timestamp": 392308720])
date1 <-- json["date"]
date2 <-- json["timestamp"]
What if I want a Custom NSDate format for a specific key ?
swift
createdAt <-- json["created_at"]?.dateFormat("yyyy-MM-dd'T'HH:mm:ssZZZZZ")
Just provide it on a case per case basis ! 🎉
Accessing JSON values
Nested values
value <-- json["nested.nested.nested.nestedValue"]
Object at index
value <-- json[12]
Combine both
value <-- json[1]?["someKey"]?[2]?["something.other"]
Looping on Array
if let collection = json.collection {
for jsonEntry in collection {
//Do something
}
}
Acknoledgments
This wouldn’t exist without YannickDot, Damien-nd and maxkonovalov
Other repos ❤️
Arrow is part of a series of lightweight libraries aiming to make developing iOS Apps a breeze :
- Layout : Stevia
- Async code : then
- JSON WebServices : ws
View on GitHub
Arrow Class Reference
View on GitHub
Classes Reference