Wrap is deprecated in favor of Swiftโs built-in Codable
API and the Codextended project. All current users are highly encouraged to migrate to Codable
as soon as possible.
Unbox | Wrap
Wrap is an easy to use Swift JSON encoder. Don't spend hours writing JSON encoding code - just wrap it instead!
Using Wrap is as easy as calling wrap()
on any instance of a class
or struct
that you wish to encode. It automatically encodes all of your typeโs properties, including nested objects, collections, enums and more!
It also provides a suite of simple but powerful customization APIs that enables you to use it on any model setup with ease.
Say you have your usual-suspect User
model:
struct User {
let name: String
let age: Int
}
let user = User(name: "John", age: 28)
Using wrap()
you can now encode a User
instance with one command:
let dictionary: [String : Any] = try wrap(user)
Which will produce the following Dictionary
:
{
"name": "John",
"age": 28
}
The first was a pretty simple example, but Wrap can encode even the most complicated structures for you, with both optional, non-optional and custom type values, all without any extra code on your part. Letโs say we have the following model setup:
struct SpaceShip {
let type: SpaceShipType
let weight: Double
let engine: Engine
let passengers: [Astronaut]
let launchLiveStreamURL: URL?
let lastPilot: Astronaut?
}
enum SpaceShipType: Int, WrappableEnum {
case apollo
case sputnik
}
struct Engine {
let manufacturer: String
let fuelConsumption: Float
}
struct Astronaut {
let name: String
}
Letโs create an instance of SpaceShip
:
let ship = SpaceShip(
type: .apollo,
weight: 3999.72,
engine: Engine(
manufacturer: "The Space Company",
fuelConsumption: 17.2321
),
passengers: [
Astronaut(name: "Mike"),
Astronaut(name: "Amanda")
],
launchLiveStreamURL: URL(string: "http://livestream.com"),
lastPilot: nil
)
And now letโs encode it with one call to wrap()
:
let dictionary: WrappedDictionary = try wrap(ship)
Which will produce the following dictionary:
{
"type": 0,
"weight": 3999.72,
"engine": {
"manufacturer": "The Space Company",
"fuelConsumption": 17.2321
},
"passengers": [
{"name": "Mike"},
{"name": "Amanda"}
],
"launchLiveStreamURL": "http://livestream.com"
}
As you can see, Wrap automatically encoded the URL
property to its absoluteString
, and ignored any properties that were nil
(reducing the size of the produced JSON).
While automation is awesome, customization is just as important. Thankfully, Wrap provides several override points that enables you to easily tweak its default behavior.
Per default Wrap uses the property names of a type as its encoding keys, but sometimes this is not what youโre looking for. You can choose to override any or all of a typeโs encoding keys by making it conform to WrapCustomizable
and implementing keyForWrapping(propertyNamed:)
, like this:
struct Book: WrapCustomizable {
let title: String
let authorName: String
func keyForWrapping(propertyNamed propertyName: String) -> String? {
if propertyName == "authorName" {
return "author_name"
}
return propertyName
}
}
You can also use the keyForWrapping(propertyNamed:)
API to skip a property entirely, by returning nil from this method for it.
You might have nested dictionaries that are not keyed on Strings
, and for those Wrap provides the WrappableKey
protocol. This enables you to easily convert any type into a string that can be used as a JSON key.
If you want the dictionary that Wrap produces to have snake_cased keys rather than the default (which is matching the names of the properties that were encoded), you can easily do so by conforming to WrapCustomizable
and returning .convertToSnakeCase
from the wrapKeyStyle
property. Doing that will, for example, convert the property name myProperty
into the key my_property
.
For some nested types, you might want to handle the wrapping yourself. This may be especially true for any custom collections, or types that have a completely different representation when encoded. To do that, make a type conform to WrapCustomizable
and implement wrap(context:dateFormatter:)
, like this:
struct Library: WrapCustomizable {
private let booksByID: [String : Book]
func wrap(context: Any?, dateFormatter: DateFormatter?) -> Any? {
return Wrapper(context: context, dateFormatter: dateFormatter).wrap(self.booksByID)
}
}
Wrap also makes it super easy to encode any enum
values that your types are using. If an enum
is based on a raw type (such as String
or Int
), all you have to do is to declare conformance to WrappableEnum
, and the rest is taken care of for you.
Non-raw type enum
values are also automatically encoded. The default behavior encodes any values that donโt have associated values as their string representation, and those that do have associated values as a dictionary (with the string representation as the key), like this:
enum Profession {
case developer(favoriteLanguageName: String)
case lawyer
}
struct Person {
let profession = Profession.developer(favoriteLanguageName: "Swift")
let hobbyProfession = Profession.lawyer
}
Encodes into:
{
"profession": {
"developer": "Swift"
},
"hobbyProfession": "lawyer"
}
To be able to easily encode any dependencies that you might want to use during the encoding process, Wrap provides the ability to supply a contextual object when initiating the wrapping process (by calling wrap(object, context: myContext
).
A context can be of Any
type and is accessible in all WrapCustomizable
wrapping methods. Here is an example, where we send in a prefix to add to a Book
โs title
:
struct Book: WrapCustomizable {
let title: String
func wrap(context: Any?, dateFormatter: DateFormatter?) -> Any? {
guard let prefix = context as? String else {
return nil
}
return [
"title" : prefix + self.title
]
}
}
let data = try wrap(object) as Data
let string = String(data: data, encoding: .utf8)
Wrap supports the following platforms:
- ๐ฑ iOS 8+
- ๐ฅ macOS 10.9+
- โ๏ธ watchOS 2+
- ๐บ tvOS 9+
- ๐ง Linux
Wrap can be easily used in either a Swift script, command line tool or in an app for iOS, macOS, watchOS, tvOS or Linux.
Either
- Drag the file
Wrap.swift
into your application's Xcode project.
or
- Use CocoaPods, Carthage or the Swift Package Manager to include Wrap as a dependency in your project.
- Install Marathon.
- Add Wrap using
$ marathon add https://github.com/JohnSundell/Wrap.git
. - Run your script using
$ marathon run <path-to-your-script>
.
- Drag the file
Wrap.swift
into your command line tool's Xcode project.
For more updates on Wrap, and my other open source projects, follow me on Twitter: @johnsundell
Also make sure to check out Unbox that letโs you easily decode JSON.