• This repository has been archived on 20/May/2021
  • Stars
    star
    732
  • Rank 61,915 (Top 2 %)
  • Language
    Swift
  • License
    MIT License
  • Created almost 9 years ago
  • Updated over 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

[DEPRECATED] The easy to use Swift JSON encoder

โš ๏ธ DEPRECATED

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.


Wrap

Unbox | Wrap

BuddyBuild CocoaPods Carthage Twitter: @johnsundell

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.

Basic example

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
}

Advanced example

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).

Customization

While automation is awesome, customization is just as important. Thankfully, Wrap provides several override points that enables you to easily tweak its default behavior.

Customizing keys

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.

Custom key types

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.

Encoding keys as snake_case

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.

Customized wrapping

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)
    }
}

Enum support

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"
}

Contextual objects

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
        ]
    }
}

String serialization

let data = try wrap(object) as Data
let string = String(data: data, encoding: .utf8)

Compatibility

Wrap supports the following platforms:

  • ๐Ÿ“ฑ iOS 8+
  • ๐Ÿ–ฅ macOS 10.9+
  • โŒš๏ธ watchOS 2+
  • ๐Ÿ“บ tvOS 9+
  • ๐Ÿง Linux

Usage

Wrap can be easily used in either a Swift script, command line tool or in an app for iOS, macOS, watchOS, tvOS or Linux.

In an application

Either

  • Drag the file Wrap.swift into your application's Xcode project.

or

In a script

  • Install Marathon.
  • Add Wrap using $ marathon add https://github.com/JohnSundell/Wrap.git.
  • Run your script using $ marathon run <path-to-your-script>.

In a command line tool

  • Drag the file Wrap.swift into your command line tool's Xcode project.

Hope you enjoy wrapping your objects!

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.

More Repositories

1

Publish

A static site generator for Swift developers
Swift
4,840
star
2

SwiftTips

A collection of Swift tips & tricks that I've shared on Twitter
3,971
star
3

Files

A nicer way to handle files & folders in Swift
Swift
2,456
star
4

Ink

A fast and flexible Markdown parser written in Swift.
Swift
2,377
star
5

Plot

A DSL for writing type-safe HTML, XML and RSS in Swift.
Swift
1,979
star
6

Unbox

[Deprecated] The easy to use Swift JSON decoder
Swift
1,956
star
7

Marathon

[DEPRECATED] Marathon makes it easy to write, run and manage your Swift scripts ๐Ÿƒ
Swift
1,863
star
8

ImagineEngine

A project to create a blazingly fast Swift game engine that is a joy to use ๐Ÿš€
Swift
1,825
star
9

SwiftPlate

Easily generate cross platform Swift framework projects from the command line
Swift
1,766
star
10

Splash

A fast, lightweight and flexible Swift syntax highlighter for blogs, tools and fun!
Swift
1,758
star
11

TestDrive

Quickly try out any Swift pod or framework in a playground
Swift
1,597
star
12

Codextended

Extensions giving Swift's Codable API type inference super powers ๐Ÿฆธโ€โ™‚๏ธ๐Ÿฆนโ€โ™€๏ธ
Swift
1,495
star
13

ShellOut

Easily run shell commands from a Swift script or command line tool
Swift
836
star
14

CollectionConcurrencyKit

Async and concurrent versions of Swiftโ€™s forEach, map, flatMap, and compactMap APIs.
Swift
730
star
15

Sweep

Fast and powerful Swift string scanning made simple
Swift
531
star
16

Playground

Instantly create Swift playgrounds from the command line
Swift
439
star
17

Require

Require optional values to be non-nil, or crash gracefully
Swift
414
star
18

XcodeTheme

My Xcode theme - Sundell's Colors
Swift
408
star
19

AsyncCompatibilityKit

iOS 13-compatible backports of commonly used async/await-based system APIs that are only available from iOS 15 by default.
Swift
378
star
20

Shapeshift

Quickly convert a folder containing Swift files into an iPad-compatible Playground
Swift
338
star
21

Identity

๐Ÿ†” Type-safe identifiers in Swift
Swift
298
star
22

SwiftBySundell

Code samples from the Swift by Sundell website & podcast
Swift
289
star
23

SwiftScripting

A list of Swift scripting tools, frameworks & examples
235
star
24

SuperSpriteKit

Extensions to Apple's SpriteKit game engine
Objective-C
224
star
25

Flow

Operation Oriented Programming in Swift
Swift
217
star
26

Xgen

A Swift package for generating Xcode workspaces & playgrounds
Swift
189
star
27

IndieSupportWeeks

A two-week effort to help support indie developers shipping apps on Apple's platforms who have been financially impacted by the COVID-19 pandemic.
182
star
28

CGOperators

Easily manipulate CGPoints, CGSizes and CGVectors using math operators
Swift
148
star
29

Animate

Declarative UIView animations without nested closures
Swift
129
star
30

SplashPublishPlugin

A Splash plugin for the Publish static site generator
Swift
92
star
31

Assert

A collection of convenient assertions for Swift testing
Swift
69
star
32

UITestingExample

Example code from my blog post about UI testing
Swift
67
star
33

Marathon-Examples

A collection of example Swift scripts that can easily be run using Marathon
Swift
55
star
34

Releases

A Swift package for resolving released versions from a Git repository
Swift
51
star
35

BlockSnippets

Xcode snippets that are very handy when working with blocks in various contexts
51
star
36

PlotPlayground

A Swift playground that comes pre-loaded with Plot, that can be used to explore the new component API.
Swift
49
star
37

SwiftKit

A collection of Swift utilities that I share across my Swift-based projects
Swift
38
star
38

UnitTestingWorkshop

Project used during my workshop "Getting started with unit testing in Swift"
Swift
36
star
39

JSUpdateLookup

A lightweight, easy to use Objective-C class to check if your iOS app has an update available
Objective-C
28
star
40

SwiftAveiro

Skeleton project for my Swift Aveiro workshop "Everyone is an API designer"
Swift
15
star
41

CloudKitChat

A demo chat application powered by CloudKit
Objective-C
14
star
42

swiftbysundell-beta-feedback

Submit your feedback on the Swift by Sundell 2.0 beta
9
star
43

JSGeometry

A set of utility functions that enables easy one-line manipulation of CoreGraphics geometry structs like CGPoint, CGSize & CGRect.
Objective-C
6
star
44

JSAutoCopy

An Objective-C category that enables automatic copying of any object
Objective-C
4
star
45

UnboxDemoPlayground

A Swift Playground that comes setup with Unbox & Wrap, used in my CocoaHeads Stockholm presentation
Swift
3
star
46

JSAutoEncodedObject

Automatically encode or decode any Objective-C object
Objective-C
3
star
47

JSLocalization

An Objective-C class that enables dynamic localization of an iOS app.
Objective-C
3
star
48

MarathonTestScriptWithDependencies

A test script with dependencies - used for Marathon's tests
Swift
2
star
49

JSObservableObject

Easily add protocol-based observation to any Objective-C class
Objective-C
2
star
50

MarathonTestScript

A Swift script that's used in Marathon's tests
Swift
1
star
51

MarathonTestPackage

A Swift package that's used in Marathon's tests
Swift
1
star